Good software documentation is clearly written.
It should be immediately obvious from the introduction what the code does, and why.
Write self-documenting code to spend less time describing how the code works.
Code structural hierarchies are often determined by functional relationships. But these relationships are often unclear to readers who are unfamiliar with the code. Documentation should thus aim to establish a linear narrative around non-linear code structures.
Establish documentation structures so that the next section builds on what was just described.
Write docs primarily for the people who will use the code. But include enough information for a technically savvy reader to follow.
Use mkdocs-material for package/project documentation. When deployed, this will create new documentation pages under docs.salo.ai/{repo-name}.
Use mkdocstrings for auto docstring generation.
Use mkdocs-jupyter to embed jupyter notebooks and cells to documentation.
Use pre-commit to enforce code formatting styles.
Use Google-style docstrings. This enables automatic code documentation generation with mkdocs.
We often use conda to manage virtual environments for each project or repository. To the extent possible, we should use conda to manage compiled libraries (like gdal, numpy) instead of relying on users to build things themselves.
When this isn’t possible, build dependencies using Docker and deploy the containers to our GCP Container Registry.
Declare import dependencies (and versions) in requirements.txt. Reference this file in the setup.py file for package installation.
Ten simple rules for quick and dirty scientific programming.