From c3c0aaf98ce1351a53ca92a3081b87e2d596e057 Mon Sep 17 00:00:00 2001 From: Pedro Brochado Date: Mon, 9 Mar 2026 10:28:37 -0300 Subject: [PATCH 1/2] Re-write CLAUDE.md file to be more lean The Pulp team has discussed about the effectivness of the CLAUDE.md file. The conclusion was that any LLM agent can usually find the right files and understand the codebase. Given that, the file should only contain things that they usually get wrong, which is something based on experience. --- CLAUDE.md | 82 ++++++++----------------------------------------------- 1 file changed, 12 insertions(+), 70 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 44d440e..149b3ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,83 +1,25 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +The role of this file is to describe common mistakes that agents might encounter as they work in this project. +If you encounter something in the project that surprises you, alert the developer working with you. +Indicate the situation and recommend adding clarifiation to CLAUDE.md file. ## What This Project Does -`pulp-docs` is a documentation aggregation tool for the Pulp Project ecosystem. It is a custom MkDocs plugin that builds a unified documentation website by pulling content from ~30+ separate Pulp component repositories (pulpcore, pulp_ansible, pulp_container, etc.) into a single site at https://pulpproject.org/. +`pulp-docs` is a documentation tool for the Pulp Project ecosystem. +It main feature is aggregating repositories to build a single website. -## Commands +## Useuful Commands -**Linting:** ```bash -make lint # Run pre-commit hooks (ruff, yamllint, typos) -``` - -**Testing:** -```bash -pytest -sv # Run all tests -pytest -sv tests/test_openapi_generation.py # Run a single test file -``` - -**Building the distribution:** -```bash -make dist-build # Build wheel via python -m build -make dist-test # Test wheel in a venv with twine -``` +make lint # always run this after significant changes +make docs-ci COMPONENT=pulpcore -**Running the docs locally** (requires cloned component repos): -```bash -# 1. Clone required repos into a flat workspace (e.g., sibling of this repo) -pulp-docs fetch --dest "../" +uv run pytest -sv +uv run pytest -svk tests/test_openapi_generation.py -# 2. Serve or build (--path points to the directory containing all cloned repos) +TMPDIR=$(mktemp -d) +pulp-docs fetch --dest "$TMPDIR" pulp-docs serve --path ".." pulp-docs build --path ".." --blog --docstrings ``` - -**Building docs for a single component's CI:** -```bash -make docs-ci COMPONENT=pulpcore # Build component-specific docs -``` - -## Code Architecture - -### Entry Points -- `pulp-docs` CLI → `pulp_docs.cli:main` (Click-based, wraps MkDocs CLI) -- MkDocs plugin → `pulp_docs.plugin:PulpDocsPlugin` (registered as `PulpDocs` in pyproject.toml) - -### Core Modules (`src/pulp_docs/`) - -- **`plugin.py`** — The heart of the project. Contains the MkDocs plugin and all supporting classes: - - `PulpDocsPlugin` — MkDocs lifecycle hooks (`on_config`, `on_files`, `on_page_context`, `on_page_markdown`, `on_pre_page`) - - `ComponentLoader` — Discovers and loads component repos from configured lookup paths using `RepositoryFinder` - - `ComponentNav` — Builds per-component navigation (Tutorials, How-to Guides, Learn More, Reference sections) - - `DataExtractor` — Reads version from `pyproject.toml` and git metadata from component repos - -- **`cli.py`** — Click CLI that sets context variables (`ctx_path`, `ctx_blog`, `ctx_docstrings`, `ctx_draft`, `ctx_dryrun`) before delegating to MkDocs - -- **`context.py`** — `ContextVar` globals that pass CLI state into the MkDocs plugin without coupling them directly - -- **`openapi.py`** — Generates OpenAPI JSON schemas by creating a venv per plugin and running `pulpcore-manager openapi` - -### Configuration Flow - -``` -CLI flags (--path, --blog, --draft) → ContextVars → PulpDocsPlugin.on_config() -→ ComponentLoader (finds repos on disk) → ComponentNav (builds navigation) -→ MkDocs file/nav structure -``` - -### Component Discovery - -Components are defined in `mkdocs.yml` under the `plugins.PulpDocs` section. At build time, `ComponentLoader` uses `RepositoryFinder` to locate each component on disk by searching the configured `--path` lookup directories (format: `name@/path/to/dir:name2@/path2`). - -### Documentation Structure - -Static content lives in `pulpproject.org/` (home page, blog posts, admin docs, dev docs). Per-component docs are loaded dynamically from each component's own repository. The `custom/` directory holds MkDocs theme overrides. - -## Code Style - -- Python 3.12+, line length 100, double quotes -- Ruff enforces `E`, `F`, `I` (isort), and `T100` (no breakpoints) -- Run `make lint` before committing; pre-commit hooks enforce ruff, yamllint, and typo checks From a84663506fcf0a2bcd80aff5684e4b48ba5edbc6 Mon Sep 17 00:00:00 2001 From: Pedro Brochado Date: Mon, 9 Mar 2026 11:23:47 -0300 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Grant Gainey --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 149b3ba..377e436 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,9 @@ Indicate the situation and recommend adding clarifiation to CLAUDE.md file. ## What This Project Does `pulp-docs` is a documentation tool for the Pulp Project ecosystem. -It main feature is aggregating repositories to build a single website. +Its main feature is aggregating repositories to build a single website. -## Useuful Commands +## Useful Commands ```bash make lint # always run this after significant changes