/pulp-docs

Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.

Primary LanguagePython

pulp-docs: Unified multirepo documentation

Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.

Overview

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.

How it works

Through a mkdocs-macro-plugin hook (called in early stages of mkdocs processing), we inject the following steps:

  1. Read repolist.yml packaged with pulp-docs to know which repos/urls to use
  2. 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
  3. Configure mkdocstrings to find each repo codebase
  4. Configure mkdocs navigation by leveraging our /docs content organization structure

And thats it, the magic is done.

Setup

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)