Skip to content

Latest commit

 

History

History
66 lines (47 loc) · 2.05 KB

README.md

File metadata and controls

66 lines (47 loc) · 2.05 KB
Raw

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.
  • 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.

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 way for daily usage:

pipx install git+https://github.com/pulp/pulp-docs --include-deps
pulp-docs serve

For development, use your prefered method!

How to override repolist.yml

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