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
  --dependency-graphs BOOLEAN  Output dependency dotgraphs and dependency
                               graph page, Requires system dependency
                               https://graphviz.org/
  --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.