Add code docs generation and deployment to GitHub Pages for A-plus.

[sayravai]

Description

What?

Add rst files for compiling A+ frontend (Python) code documentation using Sphinx autodoc, and add the workflow to deploy these docs into GitHub pages on each commit to the master branch.

Why?

Since large parts of the A+ Python code is documented using docstrings, it's a waste not to compile this information to a format which is easier to read and follow by clicking on hyperlinks. One can also easily see the source for each method/class (code and docs are linked both ways). Maybe this will also encourage developers to improve the docstring coverage.

How?

First, I created an initial set of rst files using sphinx-apidoc. These files mostly contain definitions for the automodule extension, which finds the pieces of code (at compilation time) to extract documentation from. As this "initialisation" process is only done once, one needs to create new rst files (or edit the new ones) whenever new Python files are added, or new modules are added in the existing files.

Once the set of files is created, sphinx-build is used to produce the actual html (or pdf/whatever) code from it. This build step is ran via a GitHub action so that it runs every time the master branch gets a new commit. After the build is finished, the files are deployed to GitHub Pages, and the code documentation root should be present under https://apluslms.github.io/aplus/. This page can then be linked to the main docs repo, and a similar documentation workflow can be created also for other projects besides a-plus.

Notes:

• I did this for the first time, so the aim at this point was just to get the automated process working. There is a lot of room for further tuning and improving, and for example the module index is quite a mess at the moment with all the migrations listed.
• Like mentioned above, the rst files need to be manually updated when new python files or classes are added, or these will not be included in the docs.
• The build process uses Ubuntu 22.04 and Python 3.10 as these worked (unlike 24.04 + Python 3.13), but Python versions newer than 3.10 should be tested soon.
• The GH action only triggers when pushing to the master branch, so if you're testing this yourself, change the branch name in deploy-docs.yml to reflect whatever branch you are currently working on.
• The "Search page" link on the main page seems not to produce a search page, but the search on left sidebar works.
• Most of the time on this PR was spent on getting all the paths and environment variables right (first on the local dev environment, then on the GitHub side), so I won't be surprised if something breaks when ran in production.
• Special thanks to @rkdarst for the help with sphinx workflow practices, and @murhum1 with APLUS_BASE_URL.

Testing

Remember to add or update unit tests for new features and changes.

• How to test your changes in A-plus
• How to test accessibility

What type of test did you run?

• Accessibility test using the WAVE extension.
• Django unit tests.
• Selenium tests.
• Other test. (Add a description below)
• Manual testing.

I tested the workflow in my own fork (and branch) of a-plus, so in theory it is possible that something does not work in the a-plus master branch.

The addition of docs should not affect any existing tests. The only changes to actual code in this commit were fixing the docstring list indentation in two Python files. There are still some warnings in the compilation process

Did you test the changes in

• Chrome
• Firefox
• This pull request cannot be tested in the browser.

Think of what is affected by these changes and could become broken

Translation

• Did you modify or add new strings in the user interface? (Read about how to create translation)

Programming style

• Did you follow our style guides?
• Did you use Python type hinting in all functions that you added or edited? (type hints for function parameters and return values)

Have you updated the README or other relevant documentation?

• documents inside the doc directory.
• README.md.
• Aplus Manual.
• Other documentation (mention below which documentation).

Is it Done?

• Reviewer has finished the code review
• After the review, the developer has made changes accordingly
• Customer/Teacher has accepted the implementation of the feature

Clean up your git commit history before submitting the pull request!