Documentation Process

The gpp-client documentation is built using:

  • Sphinx for documentation generation

  • Read the Docs for hosting and versioned builds

  • autodoc / autosummary for API reference generation

  • ariadne-codegen output for GraphQL models and input types

Documentation is automatically generated from both handwritten code and generated sources.

Read the Docs

Documentation is built and published automatically by Read the Docs.

Builds are triggered when:

  • Version tags are created

  • Pull requests are opened (preview builds)

Read the Docs provides separate builds for:

  • stable (latest production release)

  • latest (latest development release)

  • Tagged releases (production and development)

  • Pull request previews

The documentation UI may display a banner indicating whether the current build corresponds to a stable release, a development release, or a pull request preview. These banners are configured dynamically in conf.py using environment variables provided by Read the Docs.

Building Documentation Locally

Developers should build the documentation locally when making changes to public APIs or documentation content.

To build the documentation locally with live reload enabled:

uv run --group docs sphinx-autobuild docs/source docs/build

This command will:

  • Install documentation dependencies using the docs dependency group

  • Build the documentation

  • Start a local web server

  • Automatically rebuild documentation when files change

Once running, open the following URL in a browser:

http://127.0.0.1:8000

Warnings During Builds

It is normal to see warnings during documentation builds.

Some warnings are unavoidable due to the structure of the project:

  • Portions of the API are generated via ariadne-codegen

  • Generated models reflect the upstream GPP GraphQL schema

  • The schema is external and may introduce naming collisions or ambiguous references (for example, repeated fields named type)

As a result:

  • Certain Sphinx warnings (such as ambiguous cross-references) may appear

  • These warnings do not indicate documentation breakage

  • Builds are considered successful as long as Sphinx completes without errors

Note

If you identify warnings that indicate genuine documentation problems, please address them or raise an issue for further investigation.

Developers should focus on resolving errors and clear documentation issues, but warnings originating from generated code are expected and acceptable.