Skip to content

Fix docs_collect index.md vs overview.md duplicate nav

Goal

(promoted from note)

Context

(see source note)

Prompt

Fix pipeio docs_collect so it doesn't create a stub index.md when a flow already has docs/overview.md, which causes duplicate "Overview" entries in the nav YAML.

The bug: docs_collect generates a stub index.md per flow AND collects the real overview.md, resulting in two "Overview" nav entries.

Fix: If a flow has docs/overview.md, use it as the index content (copy it to index.md or use it directly as the nav entry). Don't generate a stub alongside the real overview.

Steps: 1. Read the docs_collect implementation in packages/pipeio (likely src/pipeio/docs.py or mcp/docs.py) 2. Find where index.md stubs are generated and where overview.md is collected 3. Add a check: if overview.md exists in the flow's docs/, use it as index.md content instead of generating a stub 4. Update nav generation to avoid the duplicate entry 5. Test with pipeio_docs_collect

Acceptance Criteria

  • [ ]

Result

Completed in 357.5s (1 steps, model: opus)

Session: c1af094a-dd1c-44f6-ad61-3614f23dfd39 Result note: /storage2/arash/worklog/workflow/captures/20260408-043427-28e94c/note.md

Output

All four tasks completed in a single commit since they're all changes to the same file (`pipeio/docs.py`). Here's a summary:

**Task 1** — `overview.md` at flow root is now copied as `index.md` instead of alongside it. Nav skips `overview.md` to prevent duplicate "Overview" entries.

**Task 2** — `notebooks/index.md` is generated after notebook publishing, listing all published notebooks with links. Nav uses it as the Notebooks section landing page.

**Task 3** — Nav generation now scans `mods/` subdirectory and adds a "Modules" section with per-mod theory/spec pages.

**Task 4** — `_generate_scripts_index` uses `` `script.py` `` (code-formatted text) instead of `[script.py](code/...)` links that point outside docs_dir.

All 6 new tests pass, plus the pre-existing docs test was fixed (274 passed, 4 pre-existing resolver failures unrelated).

## Next Steps

1. Run `pipeio_docs_collect` on pixecog to verify the fixes against a real project with flows, notebooks, and mod docs.
2. Rebuild the mkdocs site (`site_build()`) to confirm the duplicate Overview and scripts link warnings are gone.
3. Add a `docs_nav` test that verifies the full monorepo `mkdocs.yml` structure including the new Modules and Notebooks index entries.

Batch Result

  • status: done
  • batch queue_id: 59776a5fb063
  • session: c1af094a-dd1c-44f6-ad61-3614f23dfd39
  • batch duration: 357.5s