Build Your Python Project Documentation With MkDocs

This folder contains the source code and an example documentation built with MkDocs, using the Material for MkDocs theme and the mkdocstrings plugin for docstring code discovery.

The code used is intentionally kept basic and represents an unnecessary reproduction of fundamental math operations. This is done to keep the focus on documenting a Python project, rather than the project's code.

You should be able to follow the same process and use the same concepts for your own Python project with more interesting code.

Setup

To view the documentation project, navigate to source_code_final/ and install the dependencies into a new virtual environment:

Linux, macOS:

$ cd source_code_final
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ python -m pip install -r requirements.txt

Windows:

PS> cd source_code_final
PS> python -m venv venv
PS> venv\bin\Activate.ps1
(venv) PS> python -m pip install -r requirements.txt

Once you're set up and you've installed the dependencies, you can serve the project:

(venv) $ mkdocs serve

Navigate to your localhost at port 8000 to view the generated documentation.

Notes

Part of the documentation is auto-generated from docstrings in source_code_final/calculator/. The mkdocstrings package renders docstrings from module and package-level docstrings, as well as function docstrings in calculations.py.

You can find the relevant notation in docs/index.md and docs/reference.md.

The rest of the documentation is written in Markdown and split up across several files in the docs/ directory.

In this project you can see that you can create project documentation that is partly auto-generated from your docstrings, interweaved with explanatory text and best-practice project documentation structure.

There is also an associated tutorial where you can learn how to Build Your Python Project Documentation With MkDocs step-by-step.