You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
The text was updated successfully, but these errors were encountered:
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:
The text was updated successfully, but these errors were encountered: