diff --git a/README.md b/README.md index 5c16f9b5..29e44d99 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ Keep track of development news: * Follow [@DevDocs](https://twitter.com/DevDocs) on Twitter * Join the [mailing list](https://groups.google.com/d/forum/devdocs) -**Table of Contents:** [Quick Start](#quick-start) · [Vision](#vision) · [App](#app) · [Scraper](#scraper) · [Commands](#available-commands) · [Contributing](#contributing) · [License](#copyright--license) · [Questions?](#questions) +:bookmark_tabs: **Table of Contents:** [Quick Start](#quick-start) · [Vision](#vision) · [App](#app) · [Scraper](#scraper) · [Commands](#available-commands) · [Contributing](#contributing) · [License](#copyright--license) · [Questions?](#questions) -## Quick Start +##:zap: Quick Start Unless you wish to contribute to the project, I recommend using the hosted version at [devdocs.io](https://devdocs.io). It's up-to-date and works offline out-of-the-box. @@ -33,7 +33,7 @@ Finally, point your browser at [localhost:9292](http://localhost:9292) (the firs The `thor docs:download` command is used to download pre-generated documentations from DevDocs's servers (e.g. `thor docs:download html css`). You can see the list of available documentations and versions by running `thor docs:list`. To update all downloaded documentations, run `thor docs:download --installed`. -**Note:** there is currently no update mechanism other than `git pull origin master` to update the code and `thor docs:download --installed` to download the latest version of the docs. To stay informed about new releases, be sure to [watch](https://github.com/freeCodeCamp/devdocs/subscription) this repository. +:bulb: **Note:** there is currently no update mechanism other than `git pull origin master` to update the code and `thor docs:download --installed` to download the latest version of the docs. To stay informed about new releases, be sure to [watch](https://github.com/freeCodeCamp/devdocs/subscription) this repository. Alternatively, DevDocs may be started as a Docker container: @@ -46,15 +46,15 @@ docker build -t thibaut/devdocs . docker run --name devdocs -d -p 9292:9292 thibaut/devdocs ``` -## Vision +##:trophy: Vision DevDocs aims to make reading and searching reference documentation fast, easy and enjoyable. The app's main goals are to: keep load times as short as possible; improve the quality, speed, and order of search results; maximize the use of caching and other performance optimizations; maintain a clean and readable user interface; be fully functional offline; support full keyboard navigation; reduce “context switch” by using a consistent typography and design across all documentations; reduce clutter by focusing on a specific category of content (API/reference) and indexing only the minimum useful to most developers. -**Note:** DevDocs is neither a programming guide nor a search engine. All our content is pulled from third-party sources and the project doesn't intend to compete with full-text search engines. Its backbone is metadata; each piece of content is identified by a unique, "obvious" and short string. Tutorials, guides and other content that don't meet this requirement are outside the scope of the project. +:bulb: **Note:** DevDocs is neither a programming guide nor a search engine. All our content is pulled from third-party sources and the project doesn't intend to compete with full-text search engines. Its backbone is metadata; each piece of content is identified by a unique, "obvious" and short string. Tutorials, guides and other content that don't meet this requirement are outside the scope of the project. -## App +##:iphone: App The web app is all client-side JavaScript, written in [CoffeeScript](http://coffeescript.org), and powered by a small [Sinatra](http://www.sinatrarb.com)/[Sprockets](https://github.com/rails/sprockets) application. It relies on files generated by the [scraper](#scraper). @@ -65,29 +65,29 @@ Another driving factor is performance and the fact that everything happens in th DevDocs being a developer tool, the browser requirements are high: 1. On the desktop: - * Recent version of Chrome, Firefox, or Opera - * Safari 8+ - * IE / Edge 10+ + * Recent version of Chrome, Firefox, or Opera + * Safari 8+ + * IE / Edge 10+ 2. On mobile: - * iOS 8+ - * Android 4.1+ - * Windows Phone 8+ + * iOS 8+ + * Android 4.1+ + * Windows Phone 8+ This allows the code to take advantage of the latest DOM and HTML5 APIs and make developing DevDocs a lot more fun! -## Scraper +##:mag_right: Scraper -The scraper is responsible for generating the documentation and index files (metadata) used by the [app](#app). It's written in Ruby under the `Docs` module. +The scraper is responsible for generating the documentation and index files(metadata) used by the [app](#app). It's written in Ruby under the `Docs` module. There are currently two kinds of scrapers: `UrlScraper` which downloads files via HTTP and `FileScraper` which reads them from the local filesystem. They both make copies of HTML documents, recursively following links that match a set of rules and applying all sorts of modifications along the way, in addition to building an index of the files and their metadata. Documents are parsed using [Nokogiri](http://nokogiri.org). Modifications made to each document include: -* removing content such as the document structure (``, ``, etc.), comments, empty nodes, etc. -* fixing links (e.g. to remove duplicates) -* replacing all external (not scraped) URLs with their fully qualified counterpart -* replacing all internal (scraped) URLs with their unqualified and relative counterpart -* adding content, such as a title and link to the original document + * removing content such as the document structure (``, ``, etc.), comments, empty nodes, etc. + * fixing links (e.g. to remove duplicates) + * replacing all external (not scraped) URLs with their fully qualified counterpart + * replacing all internal (scraped) URLs with their unqualified and relative counterpart + * adding content, such as a title and link to the original document These modifications are applied via a set of filters using the [HTML::Pipeline](https://github.com/jch/html-pipeline) library. Each scraper includes filters specific to itself, one of which is tasked with figuring out the pages' metadata. @@ -95,7 +95,7 @@ The end result is a set of normalized HTML partials and two JSON files (index + More information about scrapers and filters is available on the [wiki](https://github.com/freeCodeCamp/devdocs/wiki). -## Available Commands +##:computer: Available Commands The command-line interface uses [Thor](http://whatisthor.com). To see all commands and options, run `thor list` from the project's root. @@ -131,13 +131,13 @@ thor assets:clean # Clean old assets If multiple versions of Ruby are installed on your system, commands must be run through `bundle exec`. -## Contributing +##:bar_chart: Contributing Contributions are welcome. Please read the [contributing guidelines](https://github.com/freeCodeCamp/devdocs/blob/master/CONTRIBUTING.md). DevDocs's own documentation is available on the [wiki](https://github.com/freeCodeCamp/devdocs/wiki). -## Copyright / License +##:clipboard: Copyright / License Copyright 2013-2018 Thibaut Courouble and [other contributors](https://github.com/freeCodeCamp/devdocs/graphs/contributors) @@ -147,6 +147,6 @@ Please do not use the name DevDocs to endorse or promote products derived from t I also wish that any documentation file generated using this software be attributed to DevDocs. Let's be fair to all contributors by giving credit where credit's due. Thanks! -## Questions? +##:email: Questions? If you have any questions, please feel free to ask them on the [mailing list](https://groups.google.com/d/forum/devdocs).