Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add reference documentation #99

Open
3 tasks
egpbos opened this issue May 19, 2021 · 0 comments
Open
3 tasks

Add reference documentation #99

egpbos opened this issue May 19, 2021 · 0 comments
Labels
documentation Improvements or additions to documentation software sustainability

Comments

@egpbos
Copy link
Collaborator

egpbos commented May 19, 2021

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation software sustainability
Projects
None yet
Development

No branches or pull requests

1 participant