Documentation¶

The documentation for remoteStorage.js is generated from reStructuredText files in the doc/ folder, as well as JSDoc code comments, which are being pulled in via special declarations in those files.

We use Sphinx to generate the documentation website, and the sphinx-js extension for handling the JSDoc part.

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 remotestoragejs.readthedocs.io.

This means that if you want to contribute to the documentation 1, 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¶

Setup¶

Install Python and PIP (likely already installed)
Install sphinx:
```
$ pip install sphinx
```
Install required extensions (from repository root):
```
$ pip install -r doc/requirements.txt
```
Install JSDoc globally via npm:
```
$ npm install -g jsdoc
```

Build¶

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.

Hint

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.

Footnotes

1: Every single bit helps other people! Even fixing a typo is worth a pull request.