Generate The Documentation

This project uses sphinx in order to generate it’s documentation & hosts them on Github Pages. There are a few steps for generating & hosting documentation.

Automatic generation of documentation

Note

For a clean/fresh clone of this repo one should execute the following command only ONCE before to the rest of the steps. The command is:

# from the repo's top directory
git worktree add docs/build/html -B gh-pages

The rest of the automatic publishing of the documentation heavily relies on git worktree feature. We expect to have a git worktree in docs/build/html/ checkout on branch gh-pages. You can verify it by the following commands:

# you should see 2 worktrees, one of the repo's top directory on your branch, i.e. ``master``, ``dev``, etc.
# and another in ``docs/build/html/`` on ``gh-pages`` branch.
git worktree list

Another way to verify it is:

# should tell you are checked-out to your branch.
git branch

cd docs/build/html/
# should tell you are checked-out to gh-pages branch.
git branch

You should execute the following commands:

# from docs/
make clean

# move to the repo top directory
cd ..
sphinx-build docs/source/ docs/build/html

And now your documentation is built! You can inspect it as follows:

firefox docs/build/html/index.html

Publishing the Documentation to Github Pages

Now since you’ve used the make clean command, the directory docs/build/html was automatically added to git worktree for the branch gh-pages which is the default branch Github <github.com> uses for the pages feature. All that is left to do is as follows:

cd docs/build/html

Now you need to verify that your working on gh-pages branch, this can be validated as follows:

# from docs/build/html
git branch

After this verification we can add all the new documentation.

# from docs/build/html
git add -A .
git commit -sm "update documentation"
git push origin gh-pages

And Your’e Done!

Highly Autonomous Documentation Generation & Publication

There is also another way which automates this procedure even further. All one has to do is simply execute the following (from the top directory of the repository)

make docs

This command will generate the documentation using sphinx. The following command will generate the documentation and publish them onto Github Pages.

make publish-docs