Writing documentation#
All contributions to documenting cellpy
is highly welcomed.
Types of documentation#
Code can be documented by several means. All are valuable. For example:
adding examples to the
examples
folderimproving the documentation in the
docs
folderimproving the doc-strings in the code
adding descriptive tests to the code
providing example data (e.g. raw-files in different formats)
tutorials on YouTube
blogs etc.
apps
Add examples to the examples folder#
The examples folder is a good place to add examples of how to
use cellpy
. The examples should be self-contained
and easy to understand. It is recommended to use Jupyter notebooks (but not required).
Another contribution could be to add example data.
Working on the main documentation#
The docs are hosted on Read the Docs
Sphinx is used to render the documentation.
Link to help: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Notebooks can also be used.
Sphinx tooling#
List of extensions used
sphinx.ext.inheritance_diagram
sphinx.ext.viewcode
sphinx.ext.napoleon
sphinx.ext.intersphinx
myst_parser
sphinx.ext.graphviz,
nbsphinx
autoapi.extension
Current HTML theme:
sphinx_book_theme
Available variables:
ProjectVersion -> writes version number
Dependencies:
python >=3.10
pip
Sphinx
pandoc
nbsphinx
myst-parser
sphinx-autoapi
graphviz
sphinx-book-theme
API documentation is created by autoapi.
Doc-strings#
Use Google-style doc-strings
In addition to the standard admonitions, you can also use:
Transferred Arguments
See Also
Tests#
Use pytest
Use descriptive test names
Use fixtures and try to keep the tests organized in a logical way
Use the
conftest.py
file to keep fixtures and other common stuffParameters and variables (e.g. filenames) can be defined in the
fdv.py
file.