Skip to content

Add reference documentation #99

@egpbos

Description

@egpbos

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions