🧩 4.5 Automated Documentation

🧩 4.5 Automated Documentation #

🔰 Tutorial #

In this module, you will learn how to automate documentation creation for your Python projects using Sphinx and Readthedocs. You will also explore writing docstrings, generating documentation in Markdown, and understanding the concept of documentation as code.

Learning Objectives:

Write documentation in Markdown
Explain what “documentation as code” means
Write a docstring for a Python function
Set up a Readthedocs account and publish a Readthedocs page

Writing Documentation in Markdown #

Markdown is a lightweight markup language that uses plain text formatting to create formatted documents. It is widely used for writing documentation because of its simplicity and ease of use.

Why Markdown?#

Simplicity: Markdown files are easy to read and write without the need for complex syntax.
Compatibility: Markdown is supported by many platforms (e.g., GitHub, Readthedocs).
Efficiency: Markdown allows you to focus on content without worrying about formatting.

Basic Markdown Syntax:#

Headings: Use # for headings.
Lists: Use - for unordered lists or 1. for ordered lists.
Code blocks: Enclose code in triple backticks.
Links: Create links with [Link text](URL).

Example Markdown Document:#

# Project Title

## Description
This is a brief description of the project.

## Installation
To install the project, run the following command:
```bash
pip install -r requirements.txt

Usage #

Run the following command to start the application:

python main.py

More about Markdown

Video Tutorial: How to Write Markdown

What Documentation as Code Means #

Documentation as code is a practice where documentation is written, version-controlled, and maintained in the same way as code. This approach encourages continuous updates, collaboration, and automation of the documentation process.

Key Points:#

Version Control: Documentation can be versioned along with code in Git.
Automation: Tools like Sphinx and Readthedocs can automatically generate documentation from the code.
Consistency: Since the documentation is written close to the code, it is easier to keep both in sync.

By treating documentation like code, it becomes part of the development workflow, allowing it to evolve as the project grows.

Video Tutorial: Documentation as Code Explained

Writing Python Docstrings #

Docstrings are comments within Python functions, classes, or modules that describe their behavior. Tools like Sphinx can extract these docstrings and generate API documentation from them.

Example of a Function Docstring:#

def multiply(a: int, b: int) -> int:
    """
    Multiplies two numbers and returns the result.

    Parameters:
    a (int): The first number.
    b (int): The second number.

    Returns:
    int: The result of multiplying a and b.
    """
    return a * b

Steps for Writing Good Docstrings:#

Start with a summary: Begin with a one-line summary of the function.
Parameters section: Describe each argument, including its type and purpose.
Returns section: Indicate what the function returns, including the type and expected value.

More Docstring Examples #

Example for a class:#

class Calculator:
    """
    A simple calculator class that supports addition and subtraction.
    """

    def add(self, a: int, b: int) -> int:
        """
        Adds two numbers.

        Parameters:
        a (int): The first number.
        b (int): The second number.

        Returns:
        int: The sum of the two numbers.
        """
        return a + b

Video Tutorial: Writing Python Docstrings

Setting Up Sphinx for Automated Documentation #

Sphinx is a documentation generator that converts reStructuredText or Markdown files into various output formats (HTML, PDF, etc.). It can extract Python docstrings to create clean, organized API documentation.

Steps to Set Up Sphinx:#

Install Sphinx:
```
pip install sphinx
```
Initialize Sphinx Project: Run sphinx-quickstart in your project folder and follow the prompts to set up the basic structure:
```
sphinx-quickstart
```
This will generate the necessary configuration files.
Configure Sphinx:
- Modify the conf.py file to include the source directory where your Python files are located.
- Example modification:
```
import os
import sys

sys.path.insert(0, os.path.abspath("../src"))
```
Add Extensions: To use Markdown files or automate docstring extraction, add extensions in conf.py:
```
extensions = ["sphinx.ext.autodoc", "myst_parser"]
```
Build the Documentation: After making changes, run:
```
make html
```
This command will generate HTML documentation in the _build/html/ directory.

Video Tutorial: Sphinx Documentation Setup

Publishing Documentation with Readthedocs #

Readthedocs is a popular platform for hosting and automatically building documentation from your repository. It integrates seamlessly with Sphinx and GitHub.

Steps to Set Up and Publish on Readthedocs:#

Create an Account: Go to Readthedocs and sign up for an account.
Connect Your Repository: After signing in, connect your GitHub repository with Readthedocs.
Add a docs/ folder: Ensure that your project contains a docs/ folder with the Sphinx configuration files (conf.py, index.rst or index.md).
Set Up Readthedocs:
- In your Readthedocs dashboard, import the project by selecting your GitHub repository.
- Follow the prompts to configure your build settings (e.g., Python version, Sphinx builder).
Build the Documentation:
- Click “Build” in Readthedocs to generate the documentation.
- Once the build is complete, your documentation will be available at a public URL.