chapter eight

8 Authoring and maintaining documentation

 

This chapter covers

  • Writing prose documentation using reStructuredText
  • Automating code documentation collection using sphinx-apidoc and sphinx-autodoc
  • Building an HTML documentation site using Sphinx
  • Publishing documentation using Read the Docs

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, 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 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.

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.

[Important]  Important

You can use the code companion (github.com/daneah/publishing-python-packages) to check your work for the exercises in this chapter.

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

8.4.5 Create visual interest and coherent structure

8.4.6 Powering up your documentation

8.5 Summary