Hosting the Documentation¶
So far, we’ve been viewing our documentation locally on our machine. But documentation is made for sharing!
Let’s commit and push your documentation. I will be using GitHub in my examples below, however you can choose to push it on other platforms such as GitLab or BitBucket.
Files to commit to git¶
You’ll notice that when we run sphinx-quickstart
, Sphinx generated a whole
bunch of files for us. Additionally, there were a number of files getting
generated under the _build
directory. You might wonder if you have to
commit all of these files.
Here’s are the files you need to add and commit to your git repository:
conf.py
make.bat
Makefile
All of the
.rst
files, basically all of the documentation you wroteAny custom files you created under
_static
or_templates
directories. If those folders are empty, then you can ignore them.
You do not need to commit anything in _build
directory.
(optional) Push to remote¶
This step is optional. If you’re not comfortable pushing your documentation right now, and want to do it at a later time, it’s fine.
(optional) Host the documentation on ReadTheDocs¶
I’m a fan of hosting documentation through ReadTheDocs. (I’m a Gold member).
Some benefits:
It’s free if your project is open source, i.e. available publicly on GitHub, GitLab, or BitBucket
You can enable “preview” builds, so ReadTheDocs can build your documentation from pull requests. You can easily review documentation changes without needing to pull and build the PR locally.
It can build from your default/main branch. So you can keep your documentation up to date.
It can also build PDF version of your documentation without needing to set up additional configuration.
Please follow the documentation at Publishing the documentation to ReadTheDocs on how to do it.
(optional) Hosting the documentation elsewhere¶
To host your documentation elsewhere, you’ll have to figure out a way
to have your documentation built, for example by running the make html
command, perhaps as part of your CI. You’ll then want to “serve” the
_build\html
. For example, you may need to copy over the output of _build\html
to the web server that hosts your documentation.
Here’s an example instructions on how to host your Sphinx documentation on GitHub pages.