Refactor docs-ng to Python and add comprehensive self-documentation

[yeoldegrove]

Refactor docs-ng to Python and add comprehensive self-documentation

What this PR does / why we need it:

This PR modernizes the docs-ng aggregation system by refactoring from bash scripts to a well-structured Python codebase with comprehensive test coverage, and adds complete self-documentation following the Diataxis framework.

Key Changes

1. Python Refactoring (Commit 2671824)

• Replaced bash scripts with Python modules: Migrated from monolithic bash scripts (aggregate-docs.sh, fetch-repo-docs.sh, transform_content.py) to a modular Python package in src/aggregation/

• New architecture:

  • src/aggregate.py - Clean CLI entry point

  • src/aggregation/ - Core package with separate concerns:

    • models.py - Type-safe data classes
    • config.py - Configuration I/O
    • fetcher.py - Repository fetching (git + local)
    • transformer.py - Content transformations
    • structure.py - Directory operations

• Improved testing: Added proper test suite with unit and integration tests:

  • tests/unit/ - Pure function tests (config, models, transformer)
  • tests/integration/ - End-to-end workflow tests
  • Test coverage for core functionality

• Cleaner project structure:

  • Moved repos-config.json to project root
  • moved all code from scripts/ to src/

2. Commit Locking Mechanism (Commit 2671824)

• Automatic commit resolution: The DocsFetcher class now automatically records the resolved commit hash when fetching from git repositories

• Reproducible builds: Configuration supports optional commit field to lock documentation to specific commits:

  {
    "name": "gardenlinux",
    "ref": "docs-ng",
    "commit": "c4b1d8d7f878fcb3e779315d28e35fcb19ae4dfb"
  }

• Easy updates: New make aggregate-update command fetches latest commits and automatically updates lock file

• Benefits:

  • CI/CD pipelines get consistent documentation
  • Documentation versions match code versions
  • No surprises from upstream doc changes
  • Easy rollback to previous states

3. Documentation Restructuring (Commit 1200581)

• Created comprehensive documentation for docs-ng itself in Diataxis structure

• 7 documentation files added to docs/reference/supporting_tools/docs-ng/:

  • Tutorial: tutorials/getting_started.md - Step-by-step setup guide

  • How-to: how-to/adding-repos.md - Repository addition guide

  • Explanation: explanation/architecture.md - System architecture deep dive

  • Reference:

    • reference/technical.md - Source code and API documentation
    • reference/testing.md - Test suite guide
    • reference/configuration.md - Complete configuration reference

  • Overview: overview/index.md - Main entry point

4. Get CI green

• several commits that fix spellchecking and linkchecking

[netlify]

✅ Deploy Preview for gardenlinux-docs ready!

Name	Link
🔨 Latest commit	bd17961
🔍 Latest deploy log	https://app.netlify.com/projects/gardenlinux-docs/deploys/69cd3458cd8e6600086baf25
😎 Deploy Preview	https://deploy-preview-26--gardenlinux-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[ByteOtter]

I guess this deprecates #24 given that the build works again now, great to see!

[ByteOtter]

Looks like it works as intended and fixes our build problem. I didn't find anything in the code that needs immediate work, so I'll approve this. Thank you. 👍🏼