8 Authoring and maintaining documentation

At the end of the previous chapter, you achieved the important milestone of publishing your package to the Python Package Index (PyPI) for others to use. The truth is that PyPI already has more than 350,000 packages and will only continue growing. Your work on the functionality, quality, and logistics of packaging has ensured that people can use it, but you’re going to need to put in some more work if you want to ensure they will use it. You already have a captive audience at CarCorp, but as you try to scale to more clients, they will come to expect more.

Documentation is one of the major hurdles to package adoption. Without ample rationale, people may not understand why they need to use your package. Even with sufficient justification, people may not understand how to use the package, even if they want to. In this chapter, you’ll learn what effective package documentation looks like and how to create a setup that will support your project as the code evolves.

8.1 Some quick philosophy on documentation

Users come seeking documentation with typically one of a few distinct goals in mind:

8.2 Starting your documentation with Sphinx

8.2.1 Automating documentation refresh during development

8.2.2 Automating extraction of code documentation

8.3 Publishing documentation to Read the Docs

8.3.1 Configuring Read the Docs

8.4 Documentation best practices

8.4.1 What to document

8.4.2 Prefer linking over repetition

8.4.3 Use consistent, empathetic language

8.4.4 Avoid assumptions and create context