Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.
This packages is:
- A
mkdocs-macros-plugin
pluget. relevant-code - A repository for common doc website asset. relevant-code
- A centralized entrypoint for installing doc-related packages/tooling. (via its own requirements)
- A CLI for doc-related tasks, like serving and building. relevant-code
The idea is that each repository should install pulp-docs
and imediatelly be able run the unified website server.
Also, this should be used for the production build.
Through a mkdocs-macro-plugin
hook (called in early stages of mkdocs processing), we inject the following steps:
- Read
repolist.yml
packaged withpulp-docs
to know which repos/urls to use - Download/Move all source code required to dir under
tempfile.gettempdir()
- Uses
../{repo}
if available OR - Uses existing cached
{tmpdir}/{repo}
if available OR - Downloads from github
- Uses
- Configure
mkdocstrings
to find each repo codebase - Configure
mkdocs
navigation by leveraging our/docs
content organization structure
And thats it, the magic is done.
Recommended of getting it up and running:
$ virtualenv --python python3.8 pulpdocs-venv
$ . pulpdocs-venv/bin/activate
$ pip install git+https://github.com/pedro-psb/pulp-docs
$ pulp-docs --help
$ pulp-docs serve
Known issues:
- doesn't work with newer versions of python, like 3.12
- doesn't work with pipx (some problem with data assets packaging)