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

At first you should verify that you are using the splendor environment & the package is installed.

conda activate splendor
splendor --version

If not installed please refer to the installation page.

Afterwards you should execute the following commands:

# from docs/
make clean

# move to the repo top directory
cd ..
sphinx-apidoc --output-dir docs/source/ src/splendor --force
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