Skip to content

Embed the API in a project website

A project website usually describes the current state of the project, while its API changes from release to release. The cpdocs ProperDocs plugin keeps the two apart: the website is built once, and every documented version of the API is published below one directory of it, the mount point. The website itself needs no versioning.

The project website lives in docs/web; the plugin builds the versioned API and mounts it:

docs_dir: docs/web

plugins:
  - search
  - cpdocs:
      mount: reference/api

The plugin options and their defaults are config: docs/cpdocs.yml, output: build and mount: reference/api. The mount directory is replaced on every build, so it must be a proper subdirectory of the site: the site root, ., .. and absolute paths are rejected.

properdocs build publishes the versions listed in cpdocs.yml. properdocs serve also documents the checked-out working tree and makes it the default, so changes to the API show up while editing, and changing a source file triggers a rebuild. A page can list the published versions with @apidocs-versions.

Pages refer to API entities with @apidocs::demo::solve; see semantic links. With checks.broken-references: fail, a reference to an entity that does not exist fails the build.

Mount nested ProperDocs sites

A root site can ask the cpdocs plugin to build nested ProperDocs projects directly into the same output tree:

plugins:
  - cpdocs:
      mount: reference/python-api
      subsites:
        - examples/basic-cpp
        - examples/python-basic

Each path is relative to the root properdocs.yml and must contain its own properdocs.yml. No separate pre-build command is needed. properdocs build writes the nested site at that same path under site_dir; properdocs serve does the same on every relevant live rebuild and gives the nested cpdocs plugin the current-working-tree semantics used by the parent development server.