@ -67,10 +67,11 @@ Follow the following steps to update documentations to their latest version:
2. Check if the license is still correct. If you update `options[:attribution]`, also update the documentation's entry in the array in [`assets/javascripts/templates/pages/about_tmpl.coffee`](../assets/javascripts/templates/pages/about_tmpl.coffee) to match.
3. If the documentation has a custom icon, ensure the icons in <code>public/icons/*your_scraper_name*/</code> are up-to-date. If you pull the updated icon from a place different than the one specified in the `SOURCE` file, make sure to replace the old link with the new one.
4. If `self.links` is defined, check if the urls are still correct.
5. Generate the docs using `thor docs:generate <doc@version>`.
6. Make sure `thor docs:generate` doesn't show errors and that the documentation still works well. Verify locally that everything works and that the categorization of entries is still good. Often, updates will require code changes in the scraper or its filters to tweak some new markup in the source website or to categorize new entries.
7. Repeat steps 5 and 6 for all versions that you updated.
8. Create a PR and make sure to fill the checklist in section B of the PR template (remove the other sections).
5. If the scraper inherits from `FileScraper` rather than `URLScraper`, follow the instructions for that scraper in [`file-scrapers.md`](../docs/file-scrapers.md) to obtain the source material for the scraper.
6. Generate the docs using `thor docs:generate <doc@version>`.
7. Make sure `thor docs:generate` doesn't show errors and that the documentation still works well. Verify locally that everything works and that the categorization of entries is still good. Often, updates will require code changes in the scraper or its filters to tweak some new markup in the source website or to categorize new entries.
8. Repeat steps 5 and 6 for all versions that you updated.
9. Create a PR and make sure to fill the checklist in section B of the PR template (remove the other sections).
## Coding conventions
@ -83,4 +84,4 @@ Check out [EditorConfig.org](https://editorconfig.org/) to learn how to make you
## Questions?
If you have any questions, please feel free to ask them on the contributor chat room on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs).
If you have any questions, please feel free to ask them on the contributor chat room on [Discord](https://discord.gg/PRyKn3Vbay).
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.
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.
@ -143,32 +152,32 @@ Contributions are welcome. Please read the [contributing guidelines](./.github/C
## Related Projects
Made something cool? Feel free to open a PR to add a new row to this table!
| [Chrome web app](https://chrome.google.com/webstore/detail/devdocs/mnfehgbmkapmjnhcnbodoamcioleeooe) | Chrome Web App which adds a shortcut to DevDocs apps page. | N/A |
| [Sublime Text plugin](https://sublime.wbond.net/packages/DevDocs) | Sublime Text plugin to search DevDocs by selection or by input. | [](https://github.com/vitorbritto/sublime-devdocs) |
| [Atom plugin](https://atom.io/packages/devdocs) | Atom plugin adding the `doc` command to search DevDocs. | [](https://github.com/masnun/atom-devdocs) |
| [gruehle/dev-docs-viewer](https://github.com/gruehle/dev-docs-viewer) | Brackets extension for searching and viewing DevDocs content. | [](https://github.com/gruehle/dev-docs-viewer) |
| [naquad/devdocs-shell](https://github.com/naquad/devdocs-shell) | GTK shell with Vim integration. | [](https://github.com/naquad/devdocs-shell) |
| [skeeto/devdocs-lookup](https://github.com/skeeto/devdocs-lookup) | Quick Emacs API lookup on DevDocs. | [](https://github.com/skeeto/devdocs-lookup) |
| [yannickglt/alfred-devdocs](https://github.com/yannickglt/alfred-devdocs) | Alfred workflow for DevDocs. | [](https://github.com/yannickglt/alfred-devdocs) |
| [waiting-for-dev/vim-www](https://github.com/waiting-for-dev/vim-www) | Vim search plugin with DevDocs in its defaults. | [](https://github.com/waiting-for-dev/vim-www) |
| [vscode-devdocs for VS Code](https://marketplace.visualstudio.com/items?itemName=akfish.vscode-devdocs) | VS Code plugin to open and search DevDocs inside VS Code. | [](https://github.com/akfish/vscode-devdocs) |
| [devdocs for VS Code](https://marketplace.visualstudio.com/items?itemName=deibit.devdocs) | VS Code plugin to open the browser to search selected text on DevDocs. | [](https://github.com/deibit/vscode-devdocs) |
| [qwfy/doc-browser](https://github.com/qwfy/doc-browser) | Native Linux app that supports DevDocs docsets. | [](https://github.com/qwfy/doc-browser) |
| [hardpixel/devdocs-desktop](https://github.com/hardpixel/devdocs-desktop) | GTK3 application for DevDocs with search integrated in the headerbar. | [](https://github.com/hardpixel/devdocs-desktop) |
| [DevDocs Tab for VS Code](https://github.com/mohamed3nan/DevDocs-Tab) | VS Code extension to search for documentation on DevDocs.io faster by displaying it in a tab inside VS Code.| [](https://github.com/mohamed3nan/DevDocs-Tab) |
Made something cool? Feel free to open a PR to add a new row to this table! You might want to discover new projects via https://github.com/topics/devdocs.
'1993, 2021, Oracle and/or its affiliates. All rights reserved.<br>Licensed under the GNU General Public License, version 2, with the Classpath Exception.<br>Various third party code in OpenJDK is licensed under different licenses.<br>Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.',
<li>Run <code>thor docs:download --installed</code> to update all downloaded documentations.
<li>To be notified about new versions, don't forget to <a href="https://github.com/freeCodeCamp/devdocs/subscription">watch the repository</a> on GitHub.
<li>The <a href="https://github.com/freeCodeCamp/devdocs/issues">issue tracker</a> is the preferred channel for bug reports and
feature requests. For everything else, use <a href="https://gitter.im/FreeCodeCamp/DevDocs">Gitter</a>.
feature requests. For everything else, use <a href="https://discord.gg/PRyKn3Vbay">Discord</a>.
<li>Contributions are welcome. See the <a href="https://github.com/freeCodeCamp/devdocs/blob/main/CONTRIBUTING.md">guidelines</a>.
<li>DevDocs is licensed under the terms of the Mozilla Public License v2.0. For more information,
see the <a href="https://github.com/freeCodeCamp/devdocs/blob/main/COPYRIGHT">COPYRIGHT</a> and
@ -36,7 +36,7 @@ app.templates.intro = """
<li>The search supports fuzzy matching (e.g. "bgcp" brings up "background-clip").
<li>To search a specific documentation, type its name (or an abbr.), then Tab.
<li>You can search using your browser's address bar — <a href="/help#browser_search">learn how</a>.
<li>DevDocs works <a href="/offline">offline</a>, on mobile, and can be installed on <a href="https://chrome.google.com/webstore/detail/devdocs/mnfehgbmkapmjnhcnbodoamcioleeooe">Chrome</a>.
<li>DevDocs works <a href="/offline">offline</a>, on mobile, and can be installed as web app.
<li>For the latest news, follow <a href="https://twitter.com/DevDocs">@DevDocs</a>.
<li>DevDocs is free and <a href="https://github.com/freeCodeCamp/devdocs">open source</a>.
Adding a documentation may look like a daunting task but once you get the hang of it, it's actually quite simple. Don't hesitate to ask for help [in Gitter](https://gitter.im/FreeCodeCamp/DevDocs) if you ever get stuck.
Adding a documentation may look like a daunting task but once you get the hang of it, it's actually quite simple. Don't hesitate to ask for help [in Discord](https://discord.gg/PRyKn3Vbay) if you ever get stuck.
**Note:** please read the [contributing guidelines](../.github/CONTRIBUTING.md) before submitting a new documentation.
@ -49,16 +49,16 @@ In addition to the [publicly-documented commands](https://github.com/freeCodeCam
Packages can also be automatically generated during the scraping process by passing the `--package` option to `thor docs:generate`.
- `thor docs:upload`
This command does two operations:
1. sync the files for the specified documentations with S3 (used by the Heroku app);
2. upload the documentations' packages to DevDocs's S3 bundle zone (used by the `thor docs:download` command).
1. sync the files for the specified documentations with S3 (used by the Heroku app);
2. upload the documentations' packages to DevDocs's S3 bundle zone (used by the `thor docs:download` command).
For the command to work, you must have the AWS CLI configured as indicated above.
**Important:** the app should always be deployed immediately after this command has finished running. Do not run this command unless you are able and ready to deploy DevDocs.
To upload all documentations that are packaged on your computer, run `thor docs:upload --packaged`.
To test your configuration and the effect of this command without uploading anything, pass the `--dryrun` option.
@ -72,21 +72,21 @@ In addition to the [publicly-documented commands](https://github.com/freeCodeCam
## Deploying DevDocs
Once docs have been uploaded via `thor docs:upload` (if applicable), you can push to the DevDocs main branch (or merge the PR containing the updates). If the Travis build succeeds, the Heroku application will be deployed automatically.
Once docs have been uploaded via `thor docs:upload` (if applicable), you can push to the DevDocs main branch (or merge the PR containing the updates). This triggers a GitHub action which starts by running the tests. If they succeed, the Heroku application will be deployed automatically.
- If you're deploying documentation updates, verify that the documentations work properly once the deploy is done. Keep in mind that you'll need to wait a few seconds for the service worker to finish caching the new assets. You should see a "DevDocs has been updated" notification appear when the caching is done, after which you need to refresh the page to see the changes.
- If you're deploying frontend changes, monitor [Sentry](https://sentry.io/devdocs/devdocs-js/) for new JS errors once the deploy is done.
- If you're deploying server changes, monitor New Relic (accessible through [the Heroku dashboard](https://dashboard.heroku.com/apps/devdocs)) for Ruby exceptions and throughput or response time changes once the deploy is done.
If any issue arises, run `heroku rollback` to rollback to the previous version of the app (this can also be done via Heroku's UI). Note that this will not revert changes made to documentation files that were uploaded via `thor docs:upload`. Try and fix the issue as quickly as possible, then re-deploy the app. Reach out to other maintainers if you need help.
If any issue arises, run `heroku rollback` to rollback to the previous version of the app (this can also be done via Heroku's UI). Note that this will not revert changes made to documentation files that were uploaded via `thor docs:upload`. Try and fix the issue as quickly as possible, then re-deploy the app. Reach out to other maintainers if you need help.
If this is your first deploy, make sure another maintainer is around to assist.
If this is your first deploy, make sure another maintainer is around to assist.
## Infrastructure
The bundled documents are available at downloads.devdocs.io and the documents themselves at documents.devdocs.io. Download and document requests are proxied to S3 buckets devdocs-downloads.s3.amazonaws.com and devdocs-documents.s3.amazonaws.com respectively.
The bundled documents are available at downloads.devdocs.io and the documents themselves at documents.devdocs.io. Download and document requests are proxied to S3 buckets devdocs-downloads.s3.amazonaws.com and devdocs-documents.s3.amazonaws.com respectively.
New proxy VMs should be created from the `devdocs-proxy` snapshot. Before adding them to the load-balancer, it's necessary to add their IP addresses to the aws:SourceIp lists for both buckets, or their requests will be rejected.
New proxy VMs should be created from the `devdocs-proxy` snapshot. Before adding them to the load-balancer, it's necessary to add their IP addresses to the aws:SourceIp lists for both buckets, or their requests will be rejected.
When creating a new proxy VM and the `devdocs-proxy` snapshot is not available, then the new vm should be provisioned as follows:
In order to keep scrapers up-to-date the `get_latest_version(opts)` method should be overridden. If `self.release` is defined, this should return the latest version of the documentation. If `self.release` is not defined, it should return the Epoch time when the documentation was last modified. If the documentation will never change, simply return `1.0.0`. The result of this method is periodically reported in a "Documentation versions report" issue which helps maintainers keep track of outdated documentations.
return'<h1>Axios</h1><p>Promise based HTTP client for the browser and node.js</p><p>Axios is a simple promise based HTTP client for the browser and node.js. Axios provides a simple to use library in a small package with a very extensible interface.</p>'
Simon Legner
2 years ago