Metadata-Version: 2.4
Name: bst-docs
Version: 0.0.4
Summary: API Reference Generator for Buildstream Projects
Author-email: Aedan McHale <aedan.mchale@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/Aedan.mchale/bst-docs
Classifier: Programming Language :: Python
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.4.1
Requires-Dist: gitpython>=3.1.50
Requires-Dist: mdformat>=1.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tqdm>=4.68.2
Requires-Dist: validators>=0.35.0
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == "dev"
Requires-Dist: prek>=0.4.4; extra == "dev"
Requires-Dist: ruff>=0.15.15; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Requires-Dist: zensical>=0.0.44; extra == "dev"
Requires-Dist: ty>=0.0.43; extra == "dev"
Dynamic: license-file

# bst-docs

This is a API reference generator in the vein of projects like [pydoc](https://docs.python.org/3/library/pydoc.html) or [doxygen](https://www.doxygen.nl/index.html).
The goal is to generate markdown documents which describe elements within a [Buildstream Project](https://buildstream.build/), 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

```shell
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
  --html-elements BOOLEAN  If true, html elements will be embedded in markdown
                           files otherwise pure Commonmark markdown will be
                           used
  --help                   Show this message and exit.
```
