How to write reStructuredText and JSDoc¶
For learning both the basics and advances features of reStructuredText, we highly recommend the reStructuredText Primer on the Sphinx website.
For JSDoc, you can find an intro as well as a detailed directive reference on their official website.
Automatic builds and publishing¶
The documentation is published via Read the Docs.
Whenever the Git repository’s
master branch is pushed to GitHub, RTD will
automatically build a new version of the site and publish it to
This means that if you want to contribute to the documentation , you don’t necessarily have to set up Sphinx and sphinx-js locally (especially for small changes). However, if you want to preview what your local changes look like when they are rendered as HTML, you will have to set up local builds first.
How to build the docs on your machine¶
Install Python and PIP (likely already installed)
$ pip install sphinx
Install required extensions (from repository root):
$ pip install -r doc/requirements.txt
Install JSDoc globally via npm:
$ npm install -g jsdoc
Run the following command to automatically watch and build the documentation:
$ npm run doc
This will start a web server, serving the HTML docs on http://localhost:8000.
The autobuild cannot watch for changes in JSDoc comments as of now, so you
will need to re-run the command, or change something in a
.rst file in
order for code documentation changes to be re-built.
|||Every single bit helps other people! Even fixing a typo is worth a pull request.|