Contributing to this Documentation¶
This documentation is powered by Sphinx and hosted by ReadTheDocs. The source for this documentation is written in reStructuredText (RST), and is located in the “docs” directory of the Antidote repo. Before contributing to the documentation, it’s worth bookmarking the RST cheatsheet for future reference. RST is fairly straightforward to use, and there’s plenty of existing examples in these docs for you to reference, but it’s not without it’s peculiarities, so keep that handy.
To contribute to the docs, the first thing you’ll want to do is fork and clone the Antidote repo so that a copy of the repo is hosted under your username. Follow the Antidote Git instructions to do this.
Once properly cloned,
cd into the local repo’s
Before continuing, you need to make sure you have a working Python installation, complete with the
pip is available in most package managers (for instance, Ubuntu uses the package name
so if you don’t have it, a quick Google search will set you straight.
Next, install the
sudo pip install virtualenv
That should be the only thing we need root permissions for - now that we have
virtualenv we can create a virtual
Python environment in the docs directory for everything else we need. Next, run the following commands to instantiate
this virtual environment, activate it, and install all of the dependencies needed to build the docs:
virtualenv venv source venv/bin/activate pip install -r requirements.txt
As long as you see the
(venv) in your terminal prompt, you’re “in” the virtual environment. If for any reason you have
to close your terminal or restart your computer, you can “re-enter” this environment by navigating to the same directory
If you got to this point, you shouldn’t have to do this again. Building the docs now is a one-liner command, which we’ll cover in the next section.
Building the Docs¶
After the setup in the previous section, we’re finally ready to build the documentation so that we have a local copy that’s been rendered from raw RST into a nice-looking HTML layout that’s precisely like the online version.
This is accomplished with the simple command:
make clean html
This creates a directory
_build/html, and renders all of the raw RST source material into the HTML version you’re
accustomed to seeing online. However, in this case, this is all done locally, so you can preview any changes you’ve made
immediately, by navigating to the file location within your browser:
Once there you can click around and take a look at the result of your changes. You can keep this tab open and continue to make
changes to the RST source - when you want to again preview those changes, re-run
make clean html and refresh the page.