Building the Documentation

So, you want to build the documentation, eh? By now I’d assume you’ve made some changes using Creating a Doc as reference (HINT: Make sure you read over it at least once).

How are docs built?

The documentation is stored on GitHub.

../_images/github.png

When changes are pushed to a branch, ReadTheDocs is notified via a webhook.

../_images/rtd.png

When this happens, it pulls the latest changes and builds the documentation internally. That then gets posted to the site you are reading now (unless you have launched the site locally).

Can I view my changes without pushing?

Absolutely! You can use a process called auto-building, which launches the documentation on your computer (only you can see this). When you launch locally, the docs are also automatically built every time you save a file in the repo. This process requires a couple tools, having SourceTree installed (for usage of git-bash), and running some scripts.

  1. Have Python 3.7+ installed
  2. Run installSphinx.sh from GitBash
  3. Run runDev.sh from GitBash

Now, when you save rst files in the docs directory, if you have localhost:8000 open in a web browser, it will automagically update.

Tell me how to publish my stuff for others!!

All you need to publish a document for this site is commit the the docs repo and push your changes to GitHub. This will automatically build the docs that are accessed via the web, and allows others to pull the updates in order to build your changes locally (like any other repository).