Description
IF IT ISN'T DOCUMENTED, IT DOESN'T EXIST.
Documentation can make or break a project. Getting it right takes effort, but that effort doesn't have to be painful. In this tutorial, we will take a multi-stage approach to documentation, starting with the fundamentals, adding complexity and style, then finishing with automated publishing to the web. We will practice a maintainer-friendly workflow that smooths out some of the rough edges of creating documentation.
It is never too early or too late to pick up good documentation techniques and tools. As such, this tutorial will have elements that are relevant to brand new Pythonistas (What does a good docstring look like? What is a type hint?) as well as long-time practitioners (How can I make my docs easier to maintain? Where can I host docs? How can I test examples in my docstrings?).
We will cover code comments, docstrings, and type annotations as ways to add documentation within your code. Next, we will add a user interface and documentation prose layer with JupyterBook, Jupyter Notebooks, and Markdown. After that, we will use Sphinx to build API documentation. Finally, we will automate the build and publish steps with GitHub Actions and GitHub Pages.