FAIR checklist - Software documentation

[edvinskis]

Essential

• Source code documentation (docstrings)
• Document your project dependencies
• Installation instructions
• User documentation

Recommended

• Developer documentation and setup
• Examples and tutorials (e.g. Jupyter Notebooks)

Optional

• Documentation tools (Sphinx, JupyterBook, Quarto)
• Build an API reference from docstrings
• Hosting (GitHub Pages, Readthedocs)

[hiddeoff]

Finished docstrings in kinetics.py, continue with other modules

[hiddeoff]

Finished all docstrings

[hiddeoff]

Trying to make sphinx + autodoc2 work but it struggles with numpy-style docstrings (sphinx-extensions2/sphinx-autodoc2#33). Does someone have experience with this?

[edvinskis]

The issue of making sphinx and autodoc2 work with NumPy-style docstrings is a known problem. Have you looked into the numpydoc extension? Numpydoc inserts a hook into Sphinx's autodoc that converts NumPy/SciPy format docstrings into a form that Sphinx can process.

https://docs.xarray.dev/en/v0.2/sphinxext/numpydoc/README.html

[edvinskis]

Here's an example for user documentation:
https://github.com/tensorflow/tensorflow

[edvinskis]

Trying to make sphinx + autodoc2 work but it struggles with numpy-style docstrings (sphinx-extensions2/sphinx-autodoc2#33). Does someone have experience with this?

Resolved with spinx.ext.napoleon

[hiddeoff]

Almost done with writing the first (quite basic) version of the docs.

• check docstrings for
  • crisprzip.matrix_expon
  • crisprzip.nucleic_acid
  • crisprzip.plotting
• Add personal info to README (names, lab/BN/TU Delft/DCC support)
• Add link to PyPi to README
• Proofread pages
• Set up GitHub Pages (@edvinskis)
• Closer to release v1.0.0:
  • Update release notes
  • Get DOI, add 'how to cite'