Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.
This packages is:
- A
mkdocs-macros-plugin
pluget. - A repository for common doc website asset.
- A centralized entrypoint for installing doc-related packages/tooling. (via its own requirements)
- A CLI for doc-related tasks, like serving and building.
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 way for daily usage:
pipx install git+https://github.com/pulp/pulp-docs --include-deps
pulp-docs serve
For development, use your prefered method!
If you want to share work you are doing in muliple forks, you can share a custom repolist.yml
which points to your forks.
Then, anyone can test them locally by overriting your repolist.yml
like so:
$ cat "path/to/my/repolist.yml"
repos:
core:
- name: pulpcore
owner: some-github-username
title: Pulp Core
branch: main
(...)
$ export PULPDOCS_MKDOCS_FILE="path/to/my/repolist.yml"
$ pulp-docs serve