API Reference Documentation¶

This section provides details on how to generate and access the API reference documentation for the castlecraft-engineer library. The API documentation is automatically generated from the docstrings within the Python source code.

Generating API Documentation with `pdoc`¶

We recommend using pdoc (specifically pdoc3, a fork of the original pdoc) to generate the API documentation. pdoc is a simple tool that creates HTML documentation directly from your Python module's docstrings and type annotations.

1. Installation¶

First, you need to install pdoc3. You can do this using uv or pip:

uv pip install pdoc3
# or
pip install pdoc3

2. Building the Documentation Locally¶

Once pdoc3 is installed, you can generate the HTML documentation by running the following command from the root of the castlecraft-engineer project (i.e., the /path/to/castlecraft-engineer directory):

pdoc --html src/castlecraft_engineer -o docs/api_reference/html

Let's break down this command: * pdoc: Invokes the pdoc3 tool. * --html: Specifies that we want to generate HTML output. * src/castlecraft_engineer: This is the path to the Python package for which we want to generate documentation. * -o docs/api_reference/html: This specifies the output directory where the generated HTML files will be placed. The documentation will be created in a subdirectory named after our package (castlecraft_engineer) inside docs/api_reference/html/.

3. Accessing the Generated Documentation¶

After running the command, the API documentation will be available in the docs/api_reference/html/ directory. You can open the main entry point of the documentation by navigating your browser to:

docs/api_reference/html/castlecraft_engineer/index.html

This file will link to the documentation for all modules, classes, and functions within the castlecraft_engineer package.

Online Hosting (Future Possibility)¶

Currently, the API documentation is primarily intended for local generation by developers and contributors. In the future, we may explore options for hosting a pre-built version of the API documentation online (e.g., using GitLab Pages or a similar service) for easier public access.

Source of Documentation¶

The content of the API documentation is derived directly from the docstrings (and type annotations) written within the Python source code files located in the src/castlecraft_engineer directory. To improve the API documentation, please ensure that all public modules, classes, methods, and functions have clear and comprehensive docstrings.

By following these steps, users and contributors can easily generate and consult the detailed API reference for castlecraft-engineer.