bst-docs

This is a API reference generator in the vein of projects like pydoc or doxygen. The goal is to generate markdown documents which describe elements within a Buildstream Project, ideally for inclusion within hosted documentation.

Usage

To build a documentation folder for a given repo: uv run bst-docs build $REPO_PATH

Or to build a documentation folder for a network repo (clones using your .netrc): uv run bst-docs build $REPO_URL

These commands will produce a folder full of markdown files which can then be imported into the documentation portal of your choosing.

An example zensical.toml has been provided to view the results in ./output, to use: uv run zensical serve

Configuration Options

Usage: bst-docs build [OPTIONS] [PATH]

  Generate documentation for a BuildStream project.

Options:
  --depth INTEGER           Depth of network crawling to perform
  --output TEXT             Destination folder for markdown files
  --clean BOOLEAN           Remove all files from cache & output directories
  --load-includes BOOLEAN   Load content from file includes
  --html-elements BOOLEAN   If true, html elements will be embedded in
                            markdown files otherwise pure Commonmark markdown
                            will be used
  --html-links BOOLEAN      If true, markdown link extensions will be
                            converted to .html and html elements will be
                            enabled
  --all-html-fixes BOOLEAN  If true, all html level fixes will be applied This
                            is designed for when html rendering will be done
                            after the fact
  --help                    Show this message and exit.