Intro

While "self-documenting code" is good and all, there're more times when you'd want to have a dedicated documentation separately from your code. This can be useful in case of studying what's happening in your code, helping with some design decisions and overall ease of use.
Rust has an auto-documentation capability built-into it. Python has pydoc, but it's very barebones. So we're going to turn to third-party packages. The most common would Sphinx, but I personally find it much trickier to use for my needs. Most of the time I just want a single command solution and get "good enough" result. pydoctor if perfect in this instance. And it will even have working search functionality!

Useful resource

Official documentation for pydoctor.

Prerequisites

Any auto-documentation package that's out there doesn't work on it's own. It's basically a glorified text parser. It traverses your code base, looks at comments, docstrings, type hints and builds a document from those. The better your docstrings and type hinting is - the better documenation you will get. Fortunately, we're living an the era of LLMs. So you can offload some of the writing to it. Microsoft Copilot was pretty good in my experience to write detailed docstrings for modules and big classes.

Setup

Installation

In order to install it, just run

pip install pydoctor

Building

Go to the folder where you want to generate documentation. Then you have 2 options:
1. run CLI command with basic settings
2. run CLI command with configured ini file.

I'd suggest to build it with the config, to maintain consistency. Main command to run to build documentation:

pydoctor --config=pydoctor.ini [path/to/project/root/folder]

Last argument is the relative path from where you’re running the command, to where pydoctor is going to use as root.

In case config doesn’t work, here’s the basic command:

pydoctor --make-html --docformat=google --theme=readthedocs --html-output=. [path/to/project/root/folder]

After --html-output= you immediately provide where output files should go to. And the last argument is the root path.

Configuration for pydoctor.ini

project-name = [name of the project]
project-base-dir =
    [path/to/project/root/folder]
add-package =
    [additional/folder]
    [additional/folder]
html-output = [./path/to/where/to/save]
intersphinx =
    https://docs.python.org/3/objects.inv
    https://twistedmatrix.com/documents/current/api/objects.inv
verbose = 1
docformat = google
theme = readthedocs
warnings-as-errors = true
privacy =
    HIDDEN:pydoctor.test
    PUBLIC:pydoctor._configparser

After generation

After the generaion has finished, go to the folder where you specified the output should be. Now just open the index.html. Here you go - you have your project documented! How cool is that?! But there's a catch! You might've noticed that the search isn't working for some reason. And the reason is that you need to run a webserver for it to work. That's just how the search implemented in pydoctor.
My approach is to make a .bat file and add just start simple

@echo off
REM Change directory to where your PyDoctor documentation is located
cd path\to\your\documentation

REM Start the Python HTTP server
python -m http.server 8000

REM Open the documentation in the default web browser
start http://localhost:8000

This way you just need to run your .bat file and it should just work! Have a good development time!