Documenting an opensource library means going the 3/4 of the way to make it accessible. I share in this article the documentation workflow I follow when I first release an open source python library like fixtup ou alfred-cli, …

After the design phase of the interfaces that I do in obsidian and prototyping in an independent spike to verify that it is feasible, I generate a skeleton from blueprint-library-pip which helps me write a maintainable library. Then comes the time to write the documentation.

Start with documentation

Documentation is a user’s first contact with a library. It is important that it reflects the thoughts of the user and not those of the developer. I find it easier to be in that mindset when I write it before the code. This allows me to ask questions without being polluted by the details of the implementation.

Writing documentation is a design exercise. I have to think about interfaces, about user needs. I’m looking to build a library that is first easy to use, then easy to understand.

Sphinx is a great documentation builder for python

I use sphinx to write documentation for an opensource python project. Sphinx is a static generator that allows you to build documentation from files in the format reStructuredText. Sphinx is a not very original choice in the python ecosystem. I find 2 benefits to it which are the simple hosting on readthedocs and the generation of the functions documentation from the code. Unfortunately the look and feel is aging in recent years compared to alternatives like hugo, gitbook ou astro - starlight

• publish documentation on readthedocs

A project built with sphinx is effortlessly hosted on readthedocs.

• configure the site to display with the theme sphinx_rtd_theme

The theme sphinx_rtd_theme is the reference theme for documentation on readthedocs. It is simple and allows you to focus on the content and not on the form.

• extract code documentation with extension sphinx.ext.autodoc

This extension retrieves the functions docstring from the code. I detail how to use it later to build the API page.

The home page and the README

The home page is the first page the user sees. She must answer 2 questions “what does this library do?” and “how do you check that it does what it claims?”. It must be used on every platform: github, pypi, readthedocs, …

• structure in 3 paragraphs as short as possible

The home page should be as concise as possible. It is a difficult exercise. The getting started will detail the implementation of the library.

• paragraph 1: present the library in one sentence
• paragraph 2: present the benefits of the library
• paragraph 3: present a code example that shows how the library is used
• present a screenshot, a screencast, … which shows a result or a fundamental aspect of this library

• share links to other areas of the project

• documentation
• package on pypi
• source code
• chat
• issue tracker

The getting started page

Getting started allows the user to test the library. This page should present the simplest possible workflow. It is this workflow that will become the standard of use over time. You have to build it carefully and structure the library accordingly. A developer should be able to replicate it in 10-15 minutes.

• break down into steps

A getting started is sequential. Each step brings learning. After following it, a developer has a clear idea of what to use in a project.

• present visual feedback at each step

Each action is accompanied by a visual result. It can be a screenshot, a screencast, a terminal extract, a moving terminal.

It is essential to capture attention. This is proof that the workflow is simple to follow.

The API page

La documentation de l’API se construit à partir du code. En python, elle est fabriqué depuis les docstring des fonctions.

• extract documentation of functions exposed to the user

• use the sphinx.ext.autodoc extension to generate API documentation

docs/source/api.rst

Api
###

This part of the documentation lists the full API reference of all public classes and functions.

.. module:: lib

.. autofunction:: hello_world

• add more and more examples in docstrings

@contextmanager
def up(fixture: str, keep_mounted_fixture: bool = False, settings: Optional[dict] = None) -> Generator[None, None, None]:
    """
    Mount a fixture to use it in a test.

    >>> with fixtup.up('thumbnail_context'):
    >>>     os.chdir(wd)
    >>>     # do something ...
    """
    pass

• review the consistency between the code and the documentation

The code and documentation are entangled in the API page. This is the ideal place to check the consistency between the 2 during code reviews.

3 examples that inspire me

• Click

The click documentation is straight to the point. The home page presents an easy-to-test example. The concepts are organized from the simplest to the most complex. They are detailed and I enjoyed digging into some of them several months after discovering click.

• Fastapi

Fastapi’s documentation has a modern look. It differs from the sphinx look used for python documentation. The homepage is self-supporting to start using fastapi. It is complete but requires a few minutes to understand how to navigate inside. The documentation is grouped in 2 Tutorial sections - User Guide and Advanced User Guide. These 2 sections are gold mines to understand fastapi.

The code snippets show the changes to be made at each step by highlighting the code, it’s nice.

• Sentry

The sentry documentation is almost useless as the portal takes us by the hand. The home page shows how to get started in 2 minutes. She then invites us to go further by presenting a dozen sections. As sentry has grown over the years well beyond its original purpose, the documentation is difficult to navigate. To find what you are looking for, you have to navigate from page to page or use the in-app links.

To conclude

Writing documentation is a long-term effort. I find myself like the code refactoring it regularly, questioning its relevance, and evaluating its obsolescence.

Pour documenter une librairie python, sphinx est un outil effiace. Il permet de construire une documentation qui tire partie du code.

The writing of the getting started and the home page are 2 essential steps to present the bookstore. They should be simple and effective. They must allow a developer to quickly understand the interest of the library and to use it in a project.