Generate API references for your python 🐍 projects !

What is pdoc3?

Pdoc3 is a powerful documentation generation tool specifically designed for Python. It automatically generates clean and readable HTML documentation from docstrings in your code. With pdoc3, you can effortlessly create professional-looking documentation for your projects, making it easier for users and collaborators to understand and utilize your code.

example

How Does pdoc3 Work?

Pdoc3 is a Python module that automates the process of generating documentation from docstrings in your code. It follows a simple and straightforward workflow to extract information from your Python modules and generate clean and readable HTML documentation.

Here's a brief overview of how pdoc3 works:

1. Parsing the Code: Pdoc3 starts by parsing your Python code. It analyzes the structure of your modules and functions to extract relevant information, such as docstrings, function signatures, and class definitions.

2. Extracting Docstrings: Docstrings are special comments placed at the beginning of functions, classes, or modules to provide documentation. Pdoc3 identifies these docstrings and extracts them for further processing. Docstrings typically contain information about the purpose, usage, and parameters of a function or class.

3. Generating HTML Documentation: Once the docstrings are extracted, pdoc3 generates HTML documentation based on the collected information. It creates a clean and organized layout that includes the module hierarchy, function descriptions, parameter details, and any additional information provided in the docstrings.

4. Customization Options: pdoc3 provides various customization options to tailor the documentation to your needs. You can specify the output directory, change the theme, and control which modules to include in the documentation generation process. These options allow you to match the documentation style with your project's requirements.

5. Serving Documentation: In addition to generating static HTML files, pdoc3 can also serve the documentation as a local web server. This feature enables you to view the documentation in real-time while making changes to your code, providing a convenient way to iterate and update the documentation as you develop your project.

Installing pdoc3

To get started with pdoc3, you need to install it. You can do this easily using pip, the Python package installer. Open your terminal and run the following command:

pip install pdoc3

Using pdoc3

• As it is very easy to use, so according to me best way to try out pdoc3 is by Exploring hence, use help command to see various options available

pdoc3 --help

However here are some basic use cases

• for docs in pdf format

pdoc3 project_location --pdf

• for docs in html format

pdoc3 project_location --html

• for docs in markdown (usefull with sphinx or mkdocs)

pdoc3 "project location" -o DIR

checkout previous blogs

• mkdocs document generator
• jupyter notebook to markdown