feat(docs): add MkDocs documentation site with showcase landing page - #91
feat(docs): add MkDocs documentation site with showcase landing page#91oto-macenauer-absa wants to merge 3 commits into
Conversation
Adds a self-contained documentation site build alongside the existing Python sources, following the knowledge-base-docs-example template: MkDocs with a custom Jinja2 theme, a showcase landing page, and a packaged release artifact. Site contents: - Landing page (data/showcase.yml -> dist/index.html) presenting the repository as a collection of reusable workflows, with a spotlight section for the Security Automation solution. - docs/index.md overview page, plus the existing docs/security/security.md rendered as a themed documentation page. - Navigation is auto-generated from page frontmatter by scripts/pack.py. Build: python scripts/pack.py # standalone build -> dist/ + dist.tar.gz python scripts/pack.py --headless # knowledge-base build (no top nav) npm run dev # live-reload dev server Documentation dependencies live in requirements-docs.txt so the product requirements.txt stays untouched. Notable adjustments to the template: - Mermaid diagrams render client-side in theme/main.html. The superfences approach needs a !!python/name YAML tag, which breaks the yaml.safe_load in scripts/pack.py, so fenced mermaid blocks are converted in the browser and degrade to plain code blocks if the CDN is unreachable. - scripts/pack.py generated a wrong marketplace.json path for pages in subdirectories (security/security.md resolved to docs/security/index.html); it now uses the full relative path. - showcase.css gains a .sc-btn--secondary variant. The existing .sc-btn--outline is white-on-dark and is unreadable on light section backgrounds. - Absolute links in docs/security/security.md (/src/..., /docs/..., /README.md) resolved to the site root and were broken both on GitHub and in the built site; they now point at GitHub blob URLs or site-relative paths. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ALSJV4Rt4tsGJnrRHuPN39
WalkthroughAdds a MkDocs documentation site with generated navigation, a styled showcase page, Mermaid rendering, marketplace metadata generation, packaged build output, and Node-based build, preview, and development commands. ChangesDocumentation site delivery
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Developer
participant run.js
participant scripts/pack.py
participant MkDocs
participant dist
Developer->>run.js: run build or preview command
run.js->>scripts/pack.py: invoke selected mode
scripts/pack.py->>MkDocs: generate config and build docs
MkDocs->>dist: write documentation pages
scripts/pack.py->>dist: render showcase and marketplace manifest
run.js->>dist: serve preview and watch source changes
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Reformat scripts/pack.py with Black (line-length 120, per pyproject.toml).
- Type fixes for `mypy .`:
* human_size divides the byte count, so start from a float instead of
reassigning a float to an int-typed variable.
* Annotate the nav accumulators in auto_generate_nav.
- Add types-PyYAML to requirements.txt so mypy resolves the yaml stubs used
by scripts/pack.py.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ALSJV4Rt4tsGJnrRHuPN39
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/pack.py (1)
1-326: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winBlack formatting check is failing.
CI reports that
scripts/pack.pywould be reformatted by Black. Runblack scripts/pack.pybefore merge.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/pack.py` around lines 1 - 326, Run Black on scripts/pack.py and apply its formatting changes throughout the file, preserving the behavior of functions such as auto_generate_nav, generate_build_configs, render_showcase, generate_marketplace_json, and main.Source: Pipeline failures
🧹 Nitpick comments (7)
theme/style.css (2)
459-464: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winHardcoded brand hex duplicates
--kb-primary, with unnecessary!important.
#77021Eis already defined as--kb-primary(line 12), but that custom property is scoped to#showcase-rootand unreachable from#topnav(under#docs-root). Consider hoisting shared brand colors to:rootso both scopes reference one source of truth. Separately,!importanthere appears unneeded — this#topnavrule has identical specificity to, and comes after, the compiled Tailwind#topnavrule, so normal cascade order already wins.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@theme/style.css` around lines 459 - 464, Update the `#topnav` styling to use the shared brand-color custom property instead of duplicating `#77021E`, making that property available from a shared :root scope while preserving any showcase-specific usage. Remove the unnecessary !important declarations from the `#topnav` background and border rules, relying on the existing cascade order.
1-2: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStylelint findings target generated Tailwind output — not worth hand-editing.
The flagged duplicate
-webkit-text-decoration, deprecatedbutton→auto, and keyword-casing issues all live inside the compiled Tailwind CSS (line 2, per thetailwindcss v4.2.2header). Hand-fixing generated/vendor output is fragile and will be overwritten on the next rebuild; consider excluding this file (or a/*! generated */-tagged pattern) from stylelint instead.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@theme/style.css` around lines 1 - 2, Exclude the generated Tailwind stylesheet from Stylelint, using its generated-file/header pattern if supported, so findings in the compiled output are ignored without modifying the CSS. Preserve linting for authored stylesheets and ensure the exclusion applies to future rebuilds of this generated file.Source: Linters/SAST tools
theme/main.html (1)
104-104: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winMermaid CDN import pinned only to major version.
mermaid@11allows any minor/patch within v11 to be served, with no integrity check. Pinning an exact version reduces the blast radius of a compromised or unexpectedly-breaking CDN release.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@theme/main.html` at line 104, Update the dynamic Mermaid import in the relevant initialization flow to pin the CDN URL to an exact Mermaid 11 minor and patch version instead of the floating `@11` range, preserving the existing module import behavior.scripts/pack.sh (1)
52-109: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoffDuplicated frontmatter/nav-generation logic across pack.py and pack.sh.
The
parse_frontmatter/auto_generate_navlogic here is a byte-for-byte port of scripts/pack.py's implementation. Any future bug fix (e.g. the mypy/edge-case fixes flagged in scripts/pack.py) must be applied twice to keep the two entrypoints in sync.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/pack.sh` around lines 52 - 109, Remove the duplicated parse_frontmatter and auto_generate_nav implementations from generate_build_configs in scripts/pack.sh. Reuse the shared implementation from scripts/pack.py or invoke that entrypoint to generate the navigation, while preserving the existing mkdocs-build.yml and headless configuration outputs.requirements-docs.txt (1)
1-2: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPin PyYAML explicitly; consider a mypy stub for
yaml.
scripts/pack.pyandscripts/pack.shbothimport yamldirectly, but it's only pulled in transitively via mkdocs. Declaring it here avoids relying on mkdocs' own dependency graph, and addingtypes-PyYAML(as a dev-only stub) would resolve the CI mypy failureLibrary stubs not installed for "yaml"at scripts/pack.py:121.📦 Proposed fix
mkdocs==1.6.1 jinja2>=3.1 +pyyaml>=6.0🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@requirements-docs.txt` around lines 1 - 2, Update the requirements declarations used by scripts/pack.py and scripts/pack.sh to explicitly include PyYAML rather than relying on mkdocs transitively, and add the types-PyYAML development stub so mypy can type-check the yaml import.Source: Pipeline failures
scripts/pack.py (2)
126-126: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMinor: prefer
next(iter(...))over a single-element slice.🧹 Proposed fix
- print(f" Auto-generated nav with {sum(len(v) if isinstance(v, dict) and isinstance(list(v.values())[0], list) else 1 for v in nav)} page(s)") + print(f" Auto-generated nav with {sum(len(v) if isinstance(v, dict) and isinstance(next(iter(v.values())), list) else 1 for v in nav)} page(s)")🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/pack.py` at line 126, Update the page-count expression in the navigation summary print statement to inspect the first dictionary value using next(iter(v.values())) instead of materializing all values with list(v.values())[0]. Preserve the existing list-type check and page-count behavior.Source: Linters/SAST tools
43-326: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoffAdd type hints/docstrings and use
logginginstead ofPer coding guidelines: public functions (
auto_generate_nav,generate_build_configs,render_showcase,generate_marketplace_json,main,run) are missing return/parameter type hints and Google-style docstrings, and the file usesprint()throughout instead oflogging.getLogger(__name__)with lazy%formatting. As per coding guidelines, "Use type hints for public functions and classes in Python 3.14", "Uselogging.getLogger(__name__)instead of print statements", and "Use Google-style docstrings for public functions and classes."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/pack.py` around lines 43 - 326, Update the public functions run, auto_generate_nav, generate_build_configs, render_showcase, generate_marketplace_json, and main with complete Python 3.14 parameter and return type hints plus Google-style docstrings. Replace all print-based status, warning, and error output in this module with a module logger created via logging.getLogger(__name__), using lazy %-style formatting; preserve existing exit behavior and messages.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/index.md`:
- Around line 20-28: Update the fenced repository-layout code block in
docs/index.md to declare the text language, preserving its existing contents.
In `@run.js`:
- Around line 66-77: Update the watchTargets array to replace the incorrect
main.py entry with scripts/pack.py, ensuring preview mode watches the build
script invoked by run.js.
In `@scripts/pack.py`:
- Around line 119-121: Add PyYAML type stubs to the type-checking dependencies
used by CI so the yaml import inside generate_build_configs passes mypy;
alternatively configure mypy to ignore missing imports for yaml, using the
project’s existing dependency or mypy configuration mechanism.
- Around line 58-64: Update human_size so the size variable is explicitly typed
to permit the float produced by division, or use a separate float variable
initialized from path.stat().st_size. Preserve the existing unit iteration,
rounding, and returned formatting while satisfying mypy’s type checking.
- Around line 98-101: In the initialization block for top_level, sections, and
section_min_order, add explicit type annotations to sections and
section_min_order that match the key and value types used throughout the script,
ensuring mypy can infer their intended dictionary shapes.
In `@scripts/pack.sh`:
- Around line 139-145: The scripts/pack.sh showcase packaging path still reads
the removed showcase.html instead of rendering data/showcase.yml. In
scripts/pack.sh lines 139-145 and 217-218, port the wrapped-HTML rendering
behavior from scripts/pack.py’s render_showcase(), including copying
showcase.css and admin/. In run.js lines 66-77, remove showcase.html from
watchTargets or replace it with the existing data watch entry.
In `@theme/main.html`:
- Around line 92-123: The Mermaid rendering flow currently falls back all
collected graphs when any render fails. Update the logic around mermaid.run and
the graphs collection to render diagrams independently or identify only failed
nodes, and replace plain code only for those failed diagram holders while
preserving successfully rendered diagrams.
- Around line 31-38: Adjust the fallback _home_href calculation in the page URL
block to remove the extra parent-directory traversal: multiply '../' by _parts
length rather than _parts length plus one, while preserving the existing
empty-URL handling and showcase_url override.
In `@theme/style.css`:
- Around line 11-441: Remove the duplicated `#showcase-root` design-system block
from theme/style.css (lines 11-441); retain showcase.css lines 455-505 as the
sole authoritative copy of the showcase additions, with no direct changes
required there unless needed to preserve those rules.
---
Outside diff comments:
In `@scripts/pack.py`:
- Around line 1-326: Run Black on scripts/pack.py and apply its formatting
changes throughout the file, preserving the behavior of functions such as
auto_generate_nav, generate_build_configs, render_showcase,
generate_marketplace_json, and main.
---
Nitpick comments:
In `@requirements-docs.txt`:
- Around line 1-2: Update the requirements declarations used by scripts/pack.py
and scripts/pack.sh to explicitly include PyYAML rather than relying on mkdocs
transitively, and add the types-PyYAML development stub so mypy can type-check
the yaml import.
In `@scripts/pack.py`:
- Line 126: Update the page-count expression in the navigation summary print
statement to inspect the first dictionary value using next(iter(v.values()))
instead of materializing all values with list(v.values())[0]. Preserve the
existing list-type check and page-count behavior.
- Around line 43-326: Update the public functions run, auto_generate_nav,
generate_build_configs, render_showcase, generate_marketplace_json, and main
with complete Python 3.14 parameter and return type hints plus Google-style
docstrings. Replace all print-based status, warning, and error output in this
module with a module logger created via logging.getLogger(__name__), using lazy
%-style formatting; preserve existing exit behavior and messages.
In `@scripts/pack.sh`:
- Around line 52-109: Remove the duplicated parse_frontmatter and
auto_generate_nav implementations from generate_build_configs in
scripts/pack.sh. Reuse the shared implementation from scripts/pack.py or invoke
that entrypoint to generate the navigation, while preserving the existing
mkdocs-build.yml and headless configuration outputs.
In `@theme/main.html`:
- Line 104: Update the dynamic Mermaid import in the relevant initialization
flow to pin the CDN URL to an exact Mermaid 11 minor and patch version instead
of the floating `@11` range, preserving the existing module import behavior.
In `@theme/style.css`:
- Around line 459-464: Update the `#topnav` styling to use the shared brand-color
custom property instead of duplicating `#77021E`, making that property available
from a shared :root scope while preserving any showcase-specific usage. Remove
the unnecessary !important declarations from the `#topnav` background and border
rules, relying on the existing cascade order.
- Around line 1-2: Exclude the generated Tailwind stylesheet from Stylelint,
using its generated-file/header pattern if supported, so findings in the
compiled output are ignored without modifying the CSS. Preserve linting for
authored stylesheets and ensure the exclusion applies to future rebuilds of this
generated file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4472d907-d10e-432d-ad0e-62475ca7da63
⛔ Files ignored due to path filters (1)
docs/assets/images/hero.pngis excluded by!**/*.png
📒 Files selected for processing (15)
.gitignoredata/showcase.ymldocs/index.mddocs/security/security.mdmarketplace.jsonmkdocs-headless.ymlmkdocs.ymlpackage.jsonrequirements-docs.txtrun.jsscripts/pack.pyscripts/pack.shshowcase.csstheme/main.htmltheme/style.css
| # ── Generate build configs ──────────────────────────────────────────────────── | ||
| def generate_build_configs(): | ||
| import yaml |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Missing type stubs for yaml break the mypy CI job.
mypy currently fails with "Library stubs not installed for yaml" here. Add types-PyYAML to the type-checking toolchain (or configure ignore_missing_imports for yaml in the mypy config) to unblock CI.
🧰 Tools
🪛 GitHub Actions: Python Check / 0_Mypy Type Check.txt
[error] 121-121: mypy: Library stubs not installed for "yaml". [import-untyped] (Hint: "python3 -m pip install types-PyYAML" or run "mypy --install-types")
🪛 GitHub Actions: Python Check / Mypy Type Check
[error] 121-121: mypy: Library stubs not installed for "yaml". [import-untyped] (Hint: "python3 -m pip install types-PyYAML" or run "mypy --install-types")
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/pack.py` around lines 119 - 121, Add PyYAML type stubs to the
type-checking dependencies used by CI so the yaml import inside
generate_build_configs passes mypy; alternatively configure mypy to ignore
missing imports for yaml, using the project’s existing dependency or mypy
configuration mechanism.
Source: Pipeline failures
| {%- if not config.extra.headless -%} | ||
| {%- if config.extra.showcase_url -%} | ||
| {%- set _home_href = config.extra.showcase_url -%} | ||
| {%- else -%} | ||
| {%- set _url_trimmed = (page.url | default('') | trim('/')) -%} | ||
| {%- set _parts = _url_trimmed.split('/') if _url_trimmed else [] -%} | ||
| {%- set _home_href = ('../' * (_parts | length + 1)) ~ 'index.html' -%} | ||
| {%- endif -%} |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## candidate files"
git ls-files | rg '(^|/)(theme/main\.html|mkdocs(\-headless)?\.yml|mkdocs(\-headless)?\.yaml)$' || true
echo
echo "## theme/main.html excerpt"
if [ -f theme/main.html ]; then
nl -ba theme/main.html | sed -n '1,120p'
fi
echo
echo "## mkdocs URL settings"
for f in mkdocs.yml mkdocs.yaml mkdocs-headless.yml mkdocs-headless.yaml; do
if [ -f "$f" ]; then
echo "--- $f ---"
rg -n "site_url|site_name|use_directory_urls|config|extra:" "$f" -A8 -B4 || true
fi
done
echo
echo "## repo docs for relevant nested page names"
git ls-files docs | rg '(\.md)$' | sed -n '1,80p'
echo
echo "## formula probe for MkDocs-style directory URL paths"
python3 - <<'PY'
from pathlib import PurePosixPath
cases = [
("docs/index.md", "index.html"),
("docs/a.md", "a/index.html"),
("docs/a/b.md", "a/b/index.html"),
("docs/docs/security/security.md", "docs/security/security/index.html"),
]
def mkdocs_html_for_relative_docs_file(path):
# Use_directory_URL convention: docs/a.md -> a/
pure = PurePosixPath(path)
# project-relative file path including docs/
parts = pure.parts
try:
idx = parts.index('docs')
rel = parts[idx+1:]
except ValueError:
rel = parts
base = "/".join(rel)
if base:
return base + "/index.html"
return "index.html"
for path, expected_href in cases:
url = expected_href.rstrip("/").split("/")
trimmed = url[0] if url else ""
parts = trimmed.split("/") if trimmed else []
current = ("../" * (len(parts) + 1)) + "index.html"
proposed = ("../" * (len(parts))) + "index.html"
print(f"{path}: expected={expected_href}: current={current}: proposed={proposed}: current_levels={len(parts)+1}: proposed_levels={len(parts)}")
PYRepository: AbsaOSS/organizational-workflows
Length of output: 305
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## theme/main.html excerpt"
sed -n '1,120p' theme/main.html | awk '{printf "%6d\t%s\n", NR, $0}'
echo
echo "## mkdocs URL/config settings"
for f in mkdocs.yml mkdocs.yaml mkdocs-headless.yml mkdocs-headless.yaml; do
if [ -f "$f" ]; then
echo "--- $f ---"
rg -n "site_url|site_name|use_directory_urls|extra|theme:|markdown_extensions:|plugins:" "$f" -A6 -B4 || true
fi
done
echo
echo "## formula probe for MkDocs-style directory URL paths"
python3 - <<'PY'
from pathlib import PurePosixPath
cases = [
("docs/index.md", "index.html"),
("docs/a.md", "a/index.html"),
("docs/a/b.md", "a/b/index.html"),
("docs/docs/security/security.md", "docs/security/security/index.html"),
]
expected_hrefs = {
"docs/index.md": "index.html",
"docs/a.md": "a/index.html",
"docs/a/b.md": "a/b/index.html",
"docs/docs/security/security.md": "docs/security/security/index.html",
}
for path, expected_href in cases:
url = expected_href.rstrip("/").split("/")
trimmed = url[0] if url else ""
parts = trimmed.split("/") if trimmed else []
current = ("../" * (len(parts) + 1)) + "index.html"
proposed = ("../" * (len(parts))) + "index.html"
print(f"{path}: expected={expected_href}: current={current}: proposed={proposed}: current_levels={len(parts)+1}: proposed_levels={len(parts)}")
PYRepository: AbsaOSS/organizational-workflows
Length of output: 7686
Remove the extra ../ from the computed home-link fallback.
With MkDocs directory URLs enabled by default, nested pages receive URLs like a/b/, so the rendered file is under a/b/ and the logo/Home link should compute ../.. //index.html from two URL segments, not three. The current count goes one level too far and makes the home link leave the built site root.
🐛 Proposed fix
- {%- set _home_href = ('../' * (_parts | length + 1)) ~ 'index.html' -%}
+ {%- set _home_href = ('../' * (_parts | length)) ~ 'index.html' -%}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {%- if not config.extra.headless -%} | |
| {%- if config.extra.showcase_url -%} | |
| {%- set _home_href = config.extra.showcase_url -%} | |
| {%- else -%} | |
| {%- set _url_trimmed = (page.url | default('') | trim('/')) -%} | |
| {%- set _parts = _url_trimmed.split('/') if _url_trimmed else [] -%} | |
| {%- set _home_href = ('../' * (_parts | length + 1)) ~ 'index.html' -%} | |
| {%- endif -%} | |
| {%- if not config.extra.headless -%} | |
| {%- if config.extra.showcase_url -%} | |
| {%- set _home_href = config.extra.showcase_url -%} | |
| {%- else -%} | |
| {%- set _url_trimmed = (page.url | default('') | trim('/')) -%} | |
| {%- set _parts = _url_trimmed.split('/') if _url_trimmed else [] -%} | |
| {%- set _home_href = ('../' * (_parts | length)) ~ 'index.html' -%} | |
| {%- endif -%} |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@theme/main.html` around lines 31 - 38, Adjust the fallback _home_href
calculation in the page URL block to remove the extra parent-directory
traversal: multiply '../' by _parts length rather than _parts length plus one,
while preserving the existing empty-URL handling and showcase_url override.
- run.js: watch scripts/pack.py (the real build entrypoint) instead of the nonexistent main.py; drop the stale showcase.html target (data/showcase.yml is already covered by the "data" entry). - scripts/pack.sh: remove. It duplicated scripts/pack.py, was referenced by nothing, and had drifted out of sync — it still read the removed showcase.html and derived wrong output paths for pages in subdirectories. - theme/main.html: render Mermaid diagrams with suppressErrors so one bad diagram no longer reverts every diagram on the page to plain code; only holders left without an SVG fall back. - theme/style.css: drop the duplicated #showcase-root block. Doc pages have no showcase markup, and the showcase page loads showcase.css, which carries the authoritative copy. Doc-page rules (topnav, nav sections) are kept. - docs/index.md: add a language hint to the repository-layout fence (MD040). Not changed: the home-link fallback in theme/main.html. With site_dir dist/docs, the showcase entry point lives one level above the MkDocs output, so the extra "../" is required. Verified against the built site — dist/docs/ index.html resolves to ../index.html and dist/docs/security/security/ index.html to ../../../index.html, both dist/index.html. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HiWDmb8CeaexLg6CsbXACi
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/pack.py`:
- Around line 130-132: Replace the inline print in the navigation-generation
flow with the module logger from logging.getLogger(__name__), using the
appropriate domain prefix and lazy % formatting. Compute the page count in a
separate variable before logging it, preserving the existing count calculation
and message content.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 8b248688-3c21-4413-a90b-315165734dc4
📒 Files selected for processing (6)
docs/index.mdrequirements.txtrun.jsscripts/pack.pytheme/main.htmltheme/style.css
💤 Files with no reviewable changes (1)
- theme/style.css
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/index.md
- theme/main.html
- run.js
| print( | ||
| f" Auto-generated nav with {sum(len(v) if isinstance(v, dict) and isinstance(list(v.values())[0], list) else 1 for v in nav)} page(s)" | ||
| ) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Files named pack.py:"
fd -a 'pack\.py$' . || true
echo
echo "Relevant scripts/pack.py excerpt:"
if [ -f scripts/pack.py ]; then
sed -n '1,180p' scripts/pack.py | nl -ba
fiRepository: AbsaOSS/organizational-workflows
Length of output: 302
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "scripts/pack.py outline and relevant excerpt:"
wc -l scripts/pack.py
sed -n '1,180p' scripts/pack.py
echo
echo "Logging/getLogger references in scripts/pack.py:"
grep -nE 'import logging|logging\.getLogger|logger =|print\(' scripts/pack.py || trueRepository: AbsaOSS/organizational-workflows
Length of output: 7515
Use the configured logger for build output.
Python files should use logging.getLogger(__name__), lazy % formatting, and a domain prefix instead of inline print statements. For this line, compute the page count separately and log it instead.
🧰 Tools
🪛 Ruff (0.15.21)
[warning] 131-131: Prefer next(iter(v.values())) over single element slice
Replace with next(iter(v.values()))
(RUF015)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/pack.py` around lines 130 - 132, Replace the inline print in the
navigation-generation flow with the module logger from
logging.getLogger(__name__), using the appropriate domain prefix and lazy %
formatting. Compute the page count in a separate variable before logging it,
preserving the existing count calculation and message content.
Source: Coding guidelines
1 participant
Release Notes
docs/is enough to publish it.requirements-docs.txt; the productrequirements.txtgains only thetypes-PyYAMLstubs needed by the type checker.docs/security/security.mdwere broken both on GitHub and in the rendered site; they now resolve correctly.Summary
Adds a self-contained documentation site to the repository, built with MkDocs and a custom Jinja2 theme (following the
knowledge-base-docs-exampletemplate). The site presents Organizational Workflows as a collection of reusable workflows, with Security Automation as a spotlight section, and rendersdocs/security/security.mdas a themed documentation page.What is added
mkdocs.yml/mkdocs-headless.ymldocs_dir: docs,site_dir: dist/docs)theme/main.html,theme/style.cssdata/showcase.yml,showcase.cssdocs/index.mddocs/assets/images/hero.pngscripts/pack.py,scripts/pack.sh,run.js,package.jsonmarketplace.jsonrequirements-docs.txtProduct
requirements.txtis untouched — documentation dependencies are kept separate.Landing page structure
Hero (repository description) → what this is (6 cards) → how adoption works (3 steps) → solutions catalogue → Security Automation spotlight (5-stage pipeline, benefits, links) → CTA → footer.
Build
Navigation is auto-generated from page frontmatter (
title,order,section) — no manualnav:maintenance.Changes to existing files
.gitignore: ignoresdist/,dist.tar.gz, generated build configs,node_modules/.docs/security/security.md: frontmatter added (title,order). Content is otherwise unchanged apart from four absolute links (/src/security/README.md,/docs/security/aquasec-night-scan-example.yml,/README.md) that resolved to the site root and were broken both on GitHub and in the built site — they now point at GitHub blob URLs or site-relative paths.Deviations from the template
pymdownx.superfencesapproach requires a!!python/name:YAML tag, which breaksyaml.safe_loadinscripts/pack.py. Fenced```mermaidblocks are therefore converted client-side intheme/main.html; if the CDN is unreachable they degrade to readable code blocks.scripts/pack.pypath fix: the manifest generator produced a wrong path for pages in subdirectories (security/security.md→docs/security/index.html). It now uses the full relative path.showcase.cssadditions: a.sc-btn--secondaryvariant (the existing.sc-btn--outlineis white-on-dark and unreadable on light section backgrounds), spacing rules for sections that stack several blocks, andscroll-margin-topso in-page anchors clear the sticky nav.Verification
Standalone build runs clean and was served locally: landing page, overview page, security page, stylesheets, and the hero asset all return 200.
dist/marketplace.jsonlists both pages with correct paths.Notes for reviewers
docs/assets/images/hero.pngis a 1.4 MB binary — swap it for a lighter or repository-specific image if preferred.dist.tar.gzonv*tags; happy to add that in a follow-up if the knowledge base should consume this repository.scripts/pack.pystarts by removingdist/, so concurrent builds clobber each other.🤖 Generated with Claude Code
https://claude.ai/code/session_01ALSJV4Rt4tsGJnrRHuPN39
Summary by CodeRabbit
New Features
Chores