Updating Documentation - staglibrary/stagpy GitHub Wiki

To update the documentation for a given release, make the changes in the relevant docs-X.Y.Z branch, and push your changes. Github Actions will automatically publish the changes to the website.

The library documentation is automatically generated from the source code using the doxygen tool.

Installing doxygen

In order to build the documentation, you will need to install doxygen from here. The documentation is tested with doxygen 1.9.6, and it is known that it does not work with version 1.8 or 1.11.

On linux, the following code should install the correct version.

  wget https://www.doxygen.nl/files/doxygen-1.9.6.linux.bin.tar.gz
  tar xzvf doxygen-1.9.6.linux.bin.tar.gz
  sudo cp doxygen-1.9.6/bin/doxygen /usr/bin/doxygen
  sudo chmod +x /usr/bin/doxygen

Building the documentation locally

To build and view the documentation locally, in the docs directory of the stagpy repository, run

doxygen

The library documentation will then be available in the directory docs/docs/ and opening the index.html file in a web browser will allow you to browse the documentation.

Updating the documentation

The automatically generated documentation comes from a variety of sources:

  • markdown files in the docs directory (e.g. getting-started.md)
  • documentation comments in source files (e.g. graph.py)
  • doxygen configuration files including Doxyfile and DoxygenLayout.xml
  • static files configured in Doxyfile (e.g. the CSS files in docs/doxygen-awesome-css)

After making a change to the source, you can rebuild the documentation locally to see the effect it has on the generated documentation.

Publishing the documentation

When we publish a new STAG release, we create a docs-X.Y.Z branch on the STAG github project where X.Y.Z is the release version. The documentation on the STAG website is automatically published from this branch.

To publish updated documentation, push to the latest docs-X.Y.Z branch, and Github Actions will automatically deploy the docs to the website.

Make sure to merge the docs branch into main in order to update future releases with the docs changes.

Troubleshooting

If the doxygen-generated docs seem incomplete and there is an error in the doxygen output saying '.py_filter: not found', then check the following:

  • the py_filter file is executable (on unix run chmod +x py_filter)
  • the py_filter file has the correct line endings (on unix run dos2unix py_filter)