Extend update-docs: verify and update relative links in the documentation - #153
Conversation
WalkthroughThis update refactors the documentation processing script into a class-based design, introduces YAML-driven configuration for markdown file mapping, and enhances link validation and rewriting. It also updates Dockerfile base images, adds a new content collection task, and introduces a configuration file for documentation structure. Minor documentation link corrections are included. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DocsProcessor
participant YAML Config
participant FileSystem
User->>DocsProcessor: Run script with repository and output paths
DocsProcessor->>YAML Config: Load update-docs-config.yaml
YAML Config-->>DocsProcessor: Return mapping config
loop For each mapping in config
DocsProcessor->>FileSystem: Read source markdown file(s)
DocsProcessor->>DocsProcessor: Process links and content
DocsProcessor->>FileSystem: Write processed file to output path
end
DocsProcessor-->>User: Processing complete (with logs)
Possibly related PRs
📜 Recent review detailsConfiguration used: .coderabbit.yaml 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
🔇 Additional comments (6)
✨ Finishing Touches
🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (4)
docs/web/Taskfile.web.yaml (1)
17-17: Consider removing --no-cache flag for better performanceThe
--no-cacheflag forces Docker to rebuild all layers, which significantly slows down builds. Remove it unless you specifically need to bypass the cache.- docker build -f docs/web/Dockerfile -t "${TAG}" --target collect --progress=plain --no-cache . + docker build -f docs/web/Dockerfile -t "${TAG}" --target collect --progress=plain .docs/web/update-docs.py (2)
293-293: Replace print with logger for consistencyUse the logger for error messages instead of print.
except yaml.YAMLError as ex: - print(ex) + self.logger.error(f"YAML parsing error: {ex}") return {}
360-365: Consider using logger for processing status messagesFor consistency, consider using the logger for status messages instead of print statements.
- print("Processing Docker Compose stacks") + self.logger.info("Processing Docker Compose stacks") self.process_docker_directory("docker", "docker") for source, target, weight in self.markdown_locations: - print(f"Processing {source} ==> {target}") + self.logger.info(f"Processing {source} ==> {target}") self.process_location(source, target, weight)docs/web/update-docs-config.yaml (1)
4-6: Prefer key-based objects over positional tuples for long-term maintainabilityUsing 3-element arrays forces every consumer (and every future reader) to remember that index 0 = source, 1 = target, 2 = weight. A dictionary-style layout is self-describing and less error-prone.
Example rewrite:
-locations: - - ["README.md", "_index.md", 0] +locations: + - source: "README.md" + target: "_index.md" + weight: 0Consider switching before this file gains more entries.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/ai/README.md(1 hunks)docs/web/Dockerfile(3 hunks)docs/web/Taskfile.web.yaml(2 hunks)docs/web/update-docs-config.yaml(1 hunks)docs/web/update-docs.py(3 hunks)
🔇 Additional comments (8)
docs/web/Dockerfile (1)
16-16: Ensure compatibility with Hugo v0.148.1 upgradeYou’ve bumped Hugo from 0.136.5→0.148.1 in docs/web/Dockerfile (lines 16 and 38). Before merging, please verify your site’s code and configuration against the breaking changes introduced between 0.136 and 0.148:
- Migrate the deprecated
.Site.Authorfield to[params.author]in your site config- Replace any
.File.Pathchecks with.RelPermalink- Audit taxonomy/front-matter options:
menuTitle→linkTitle, movedescriptionto page front matter- Swap out removed shortcodes (e.g.
swagger→openapi)- Update any template references to
.Errin resource pipelines to use Hugo’stryfunction- Review possible Markdown rendering differences (Blackfriday→Goldmark)
- Confirm all third-party themes and custom shortcodes are updated for Hugo v0.148
• Test the site locally against v0.148.1 and consult the Hugo release notes for detailed migration guidance.
docs/ai/README.md (1)
27-27: Confirmed: docs/ai/open-models.md link is valid and no legacy file remains
- docs/ai/open-models.md was found in the same directory.
- No docs/ai/models.md file exists, so there’s nothing to clean up.
docs/web/Taskfile.web.yaml (1)
9-23: New collect task looks goodThe task properly extracts markdown and YAML content from the Docker build's collect stage.
docs/web/update-docs.py (3)
14-55: Well-structured class-based refactoringThe refactoring to use a
DocsProcessorclass with proper initialization, logging setup, and configuration loading is a significant improvement over the previous procedural approach.
67-79: Link extraction regex looks comprehensiveThe regex pattern correctly identifies markdown links and filters out absolute URLs, anchors, and mailto links.
98-163: Robust link updating logicThe link updating function properly handles:
- Anchor preservation
- Directory vs file targets
- Relative path calculations
- Missing targets with appropriate warnings
docs/web/update-docs-config.yaml (2)
13-14: Duplicate weight values may lead to unstable menu orderingBoth
ansible/README.mdandterraform/README.mduseweight: 0, as does the rootREADME.md.
If your site generator relies on unique weights to sort siblings, the final order can vary between builds.Confirm whether duplicates are intentional; if not, assign distinct weights or rely on natural file order.
8-18: Configuration format confirmedRan the suggested smoke test against
docs/web/update-docs-config.yamland verified every entry inlocationsis a 3-element list. No changes required.
5a805a8 to
e7c2e6d
Compare
Summary by CodeRabbit