Documentation#

This article outlines the documentation standards for the pyquations project. All contributors are expected to follow these guidelines to ensure the project maintains clear, consistent, and comprehensive documentation.

Documentation Expectations#

All contributions to the pyquations project must include proper documentation. This includes:

  • Adding or updating docstrings for all new or modified functions.

  • Ensuring that the documentation is clear, concise, and follows the Google-style format.

  • Providing examples and references where applicable.

Installing Documentation Dependencies#

The pyquations project uses Sphinx to generate documentation. The required tools are included in the docs optional dependency group. To install the documentation dependencies, run:

pip install -e .[docs]

This will install all the necessary tools to build and maintain the documentation.

Writing Docstrings#

All functions in the pyquations project must include Google-style docstrings. These docstrings provide detailed information about the function’s purpose, parameters, return values, errors raised, and usage examples. Following this standard ensures that the documentation is consistent and easy to understand.

Each function’s docstring should include the following sections when applicable:

  1. Description: A brief overview of what the function does.

  2. Args: A list of all parameters, including their types, default values (if any), and a short description of their purpose.

  3. Returns: A description of the return value, including its type.

  4. Raises: A list of exceptions the function may raise, along with the conditions under which they are raised.

  5. Examples: One or more usage examples demonstrating how to call the function.

  6. References: Links or citations to external resources or related documentation.

Building the Documentation Locally#

To build the documentation locally, use the docs/build_docs.py script. This script generates the HTML documentation using Sphinx.

Run the following command to build the documentation:

python docs/build_docs.py

Once the build is complete, open the generated HTML files in the docs/_build/html folder. This will allow you to preview the documentation and ensure that it renders correctly.

Pull Requests#

The documentation is automatically built and validated on pull requests. If any warnings or errors are detected during the build process, the pull request will be blocked until they are resolved. This ensures that all contributions meet the project’s documentation standards before being merged.