Skip to content

Feature/doc update#4

Open
OmerRastgar wants to merge 3 commits into
OWASP:mainfrom
OmerRastgar:feature/doc-update
Open

Feature/doc update#4
OmerRastgar wants to merge 3 commits into
OWASP:mainfrom
OmerRastgar:feature/doc-update

Conversation

@OmerRastgar

Copy link
Copy Markdown

Key Changes

  • Documentation Site: Set up MkDocs (Material theme, Mermaid, mkdocstrings) with standard pillars (architecture, developer, labs, ops, security, community, releases).
  • Automated QA Pipeline: Integrated markdownlint, cspell (spellcheck), and lychee (link check) into the docs-quality.yml CI workflow.
  • Custom Validation: Added check-codeblocks.py and check-doc-coverage.py scripts to the test suite (exposed via Makefile).
  • Path Sync Fixes: Fixed sync-docs.py to correctly rewrite relative paths for nested assets and decoupled docs/README.md from the root.
  • CD Pipeline: Added docs.yml workflow to handle automatic compilation and deployment to GitHub Pages.

Verification Results

  • Run make check-docs / make check-doc-coverage locally to verify.
  • All routes, syntax, and markdown code blocks are verified clean.
  • Path-filtering in CI confirmed working.

    - Set up MkDocs with Material theme, Mermaid diagrams, mkdocstrings, search
    - Create full doc structure: architecture, developer, labs, ops, security, community, releases
    - Add doc quality tooling: markdownlint, cspell, lychee configs + CI workflows
    - Add scripts/check-codeblocks.py and scripts/check-doc-coverage.py for automated validation
    - Add CI workflows: docs-quality.yml (lint/link/spell/coverage) and docs.yml (deploy to Pages)
    - Add doc standards and contributing guides
    - Remove obsolete files: workshop-cloud-llm-setup.md (added to cloud-setup.md)
    - Update root README, CONTRIBUTING.md, Makefile, pyproject.toml, pytest.ini, .gitignore
    - Remove docs/README.md from sync-docs.py (decoupled from root README)
    - Fix sync-docs.py to rewrite relative paths correctly for nested synced files
    - Fix remaining root README.md reference to old workshop-cloud-llm-setup.md
    - Add coverage script and linter triggers to docs-quality.yml path filters
    - Add pymdown-extensions to docs.yml deploy workflow dependencies
    - Add check-doc-coverage target to Makefile and include in check-docs
    - All routes, modules, code blocks verified clean locally
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant