Tutorial

This guide will go over the basics of the project.

Make sure that you’ve already installed it.

Note

If you have installed sphinx-versions with pipenv (which you should), you need to prefix your sphinx-versioning commands with pipenv run ... or execute them in your virtualenv (see pipenv documentation for more information on this matter).

Building Docs Locally

Before we begin make sure you have some Sphinx docs already in your project. If not, read First Steps with Sphinx first. If you just want something quick and dirty you can do the following:

git checkout -b feature_branch master  # Create new branch from master.
mkdir docs  # All documentation will go here (optional, can be anywhere).
echo "master_doc = 'index'" > docs/conf.py  # Create Sphinx config file.
echo -e "Test\n====\n\nSample Documentation" > docs/index.rst  # Create one doc.
git add docs
git commit
git push origin feature_branch  # Required.

Note

It is required to push doc files to origin. sphinx-versions only works with remote branches/tags and ignores any local changes (committed, staged, unstaged, etc). If you don’t push to origin sphinx-versions won’t see them. This eliminates race conditions when multiple CI jobs are building docs at the same time.

Build All Versions

Now that you’ve got docs pushed to origin and they build fine with sphinx-build let’s try building them with sphinx-versions:

sphinx-versioning build -r feature_branch docs docs/_build/html
open docs/_build/html/index.html

More information about all of the options can be found at Settings or by running with --help but just for convenience:

  • -r feature_branch tells the program to build our newly created/pushed branch at the root of the “html” directory. We do this assuming there are no docs in master yet. Otherwise you can omit this argument.
  • docs/_build/html is the destination directory that holds generated HTML files.
  • The final docs argument is the directory where we put our RST files in, relative to the git root (e.g. if you clone your repo to another directory, that would be the git root directory). You can add more relative paths if you’ve moved the location of your RST files between different branches/tags.

The command should have worked and your docs should be available in docs/_build/html/index.html with a “Versions” section in the sidebar.

Note

You can add a -P pdf-file-name.pdf option to also generate a pdf of all versions of your documentation