-
Notifications
You must be signed in to change notification settings - Fork 1
Description
Following #93, item [documentation_interface], we should add documentation for how to use our classes and functions.
The best way to do this would be to use an automatic documentation generation tool like Sphinx. Sphinx will generate class, method, function and module documentation HTML files from the docstrings in the Python code.
We could set up Sphinx by copy pasting the NLeSC Python template setup here: https://github.com/NLeSC/python-template/tree/main/%7B%7Bcookiecutter.directory_name%7D%7D/docs
Or maybe it's easier to do it from scratch, I have no preference.
After we set that up, we could publish the generated docs on Readthedocs or on GitHub pages. In the latter case, the autogeneration can be run from a separate CI task on master that uploads on edits.
Note that after this has all been set up, we may have a site, but we still need to fill it up with actual documentation :)
Running PyTest in "very strict" mode actually gives warnings when things lack a docstring, so running that (and then also fixing the issues) as suggested in #95 would probably be the most important part of this issue.
So, to summarize, this issue needs the following steps:
- Setup Sphinx
- Publish docs on readthedocs or GitHub Pages; in the latter case, also setup CI to auto refresh its contents
- Actually write the documentation :) Could use PyTest "very strict" mode to find gaps in existing docs.