Tools that will help document your project#

Creating an up-to-date, meaningful, easily usable documentation is not trivial. This article shortly reviews tools that could help automate the process. I focus only on Python tools that can be used for internal documentation. For more details check the pdf file or the original post.

pdoc3 - the semi-automatic solution#

Python package pdoc provides types, functions, and a command-line interface for accessing public documentation of Python modules, and for presenting it in a user-friendly, industry-standard open format. It is best suited for small- to medium-sized projects with tidy, hierarchical APIs.

pdoc extracts documentation of:

  • modules (including submodules),

  • functions (including methods, properties, coroutines …),

  • classes, and

  • variables (including globals, class variables, and instance variables).

Documentation is extracted from live objects’ docstrings using Python’s __doc__ attribute. Documentation for variables is found by examining objects’ abstract syntax trees.

MkDocs — the manual solution#

Project documentation with Markdown. MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial, then check the User Guide for more information.

Read the Docs#

Read the Docs simplifies software documentation by building, versioning, and hosting of your docs, automatically. Treating documentation like code keeps your team in the same tools, and your documentation up to date.

🔄 Up to date documentation

Whenever you push code to Git, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. Get started with our tutorial.

🗂️ Documentation for every version

Read the Docs can host multiple versions of your docs. Keep your 1.0 and 2.0 documentation online, pulled directly from Git. Start hosting all your versions.

First time here?#

We have a few places for you to get started:

🚀 Read the Docs tutorial

Take the first practical steps with Read the Docs.

🚀 Example projects

Start your journey with an example project to hit the ground running.

🚀 All tutorials

Using documentation tools like Sphinx or MkDocs for the first time or importing an existing project? We have the tutorials to get you started!