Build Your Python Project Documentation With MkDocs

Python

In this tutorial, you’ll learn how to quickly build documentation for a Python package using MkDocs and mkdocstrings. These tools allow you to generate nice-looking and modern documentation from Markdown files and your code’s docstrings.

Maintaining auto-generated documentation means less effort because you’re linking information between your code and the documentation pages. However, good documentation is more than just the technical description pulled from your code! Your project will appeal more to users if you guide them through examples and connect the dots between the docstrings.

The Material for MkDocs theme makes your documentation look good without any extra effort and is used by popular projects such as Typer CLI and FastAPI.

In this tutorial, you’ll:

Work with MkDocs to produce static pages from Markdown
Pull in code documentation from docstrings using mkdocstrings
Follow best practices for project documentation
Use the Material for MkDocs theme to make your documentation look good
Host your documentation on GitHub Pages

If you use the auto-generation features of MkDocs together with mkdocstrings, then you can create good documentation with less effort. Start your documentation with docstrings in your code, then build it into a deployed and user-friendly online resource that documents your Python project.

Ready to go? Then click the link below to get the source code for the project:

Get Source Code: Click here to get access to the source code that you’ll use to build your documentation.

Demo

In this tutorial, you’ll build project documentation that’s partly auto-generated from docstrings in your code. The example code package is intentionally simplistic, so you can focus your attention on learning how to use MkDocs and the associated libraries.

After you set up your project documentation locally, you’ll learn how to host it on GitHub Pages, so it’ll be available for everyone to see:

You can use the example project documentation that you’ll build in this tutorial as a blueprint to create documentation for your own Python projects.

Project Overview

You’ll build project documentation for a toy package called calculator that contains only one module named calculations.py, which has a couple of example Python functions.

Note: The provided code doesn’t offer any new functionality and is only meant as a basis to learn how to use existing project code to build your documentation.

You’ll follow a guideline for project documentation called the Diátaxis documentation framework, which has widespread adoption in the Python community and is used by large projects such as Django and NumPy.

This system suggests splitting up your documentation into four different parts with different orientations:

Tutorials: Learning-oriented
How-To Guides: Problem-oriented
Reference: Information-oriented
Explanation: Understanding-oriented

Splitting your project documentation into these four different purposes with different orientations will help you create comprehensive documentation for your Python project.

From a technical perspective, you’ll build your documentation using three Python packages:

MkDocs for building static pages from Markdown
mkdocstrings for auto-generating documentation from docstrings in your code
Material for MkDocs for styling your documentation

When you want to use MkDocs for auto-generating parts of your documentation from your docstrings, you’ll need to add the mkdocstrings package.

Note: Sphinx, another popular tool for Python project documentation, can auto-generate text from your docstrings without additional extensions. However, Sphinx primarily uses reStructuredText instead of Markdown and is overall less straightforward to work with than MkDocs.

You don’t absolutely need to add the Material for MkDocs theme for building your project documentation, but it’ll help to render the documentation in a user-friendly manner.

Read the full article at https://realpython.com/python-project-documentation-with-mkdocs/ »

[ Improve Your Python With 🐍 Python Tricks 💌 – Get a short & sweet Python Trick delivered to your inbox every couple of days. >> Click here to learn more and see examples ]