mirrors
/
devdocs
mirror of https://github.com/freeCodeCamp/devdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source 
Improved README.md
pull/782/head
Hero™ 7 years ago
parent d48396de57
commit df8bf1a8e6
1 changed files with 23 additions and 23 deletions
Show Stats Download Patch File Download Diff File

34
README.md
Unescape View File

@ -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).
@ -75,19 +75,19 @@ DevDocs being a developer tool, the browser requirements are high:
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 (`<html>`, `<head>`, 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 (`<html>`, `<head>`, 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).

Write Preview
Loading…
Cancel
Save