feat: update gendocs to handle old version#2610
Conversation
Implemented a `versions.html` page to list all available documentation versions and added a static version selector link to replace the deprecated dynamic dropdown. Incorporated legacy support for older Hugo APIs and fixed broken image paths in configuration files to ensure consistency across documentation releases.
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the documentation generation process by modernizing how different versions are presented and maintained. It introduces a centralized page for version selection, improves compatibility with older Hugo versions, and ensures that image assets are correctly referenced across all generated documentation, leading to a more robust and user-friendly documentation experience. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the documentation generation script (gendocs.sh) by introducing version management capabilities. It now limits the number of major versions kept, adds functions to replace the dynamic version selector with a static link to a new versions.html page, and addresses deprecated Hugo API calls for older branches. A new versions.html page is dynamically generated to list all available documentation versions, and the root index.html redirects to the latest version. Review comments suggest improving the maintainability of the generated versions.html by externalizing the HTML/CSS content from the shell script, making the keeplast variable a named constant, and using CSS classes instead of inline styles for better maintainability.
| cat <<EOF >${versiondir}/versions.html | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <title>Pipelines as Code - All Versions</title> | ||
| <meta charset="utf-8"> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
| <style> | ||
| :root { | ||
| --bg: #0d1117; | ||
| --surface: #161b22; | ||
| --border: #30363d; | ||
| --text: #e6edf3; | ||
| --text-muted: #8b949e; | ||
| --accent: #58a6ff; | ||
| --green: #3fb950; | ||
| --green-bg: rgba(63,185,80,0.15); | ||
| --yellow: #d29922; | ||
| --yellow-bg: rgba(210,153,34,0.15); | ||
| } | ||
| @media (prefers-color-scheme: light) { | ||
| :root { | ||
| --bg: #f6f8fa; | ||
| --surface: #ffffff; | ||
| --border: #d0d7de; | ||
| --text: #1f2328; | ||
| --text-muted: #656d76; | ||
| --accent: #0969da; | ||
| --green: #1a7f37; | ||
| --green-bg: rgba(26,127,55,0.1); | ||
| --yellow: #9a6700; | ||
| --yellow-bg: rgba(154,103,0,0.1); | ||
| } | ||
| } | ||
| * { box-sizing: border-box; margin: 0; padding: 0; } | ||
| body { | ||
| font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; | ||
| background: var(--bg); | ||
| color: var(--text); | ||
| min-height: 100vh; | ||
| display: flex; | ||
| justify-content: center; | ||
| padding: 60px 20px; | ||
| } | ||
| .container { max-width: 520px; width: 100%; } | ||
| .header { | ||
| display: flex; | ||
| align-items: center; | ||
| gap: 12px; | ||
| margin-bottom: 32px; | ||
| } | ||
| .logo { | ||
| width: 40px; height: 40px; | ||
| background: var(--accent); | ||
| border-radius: 10px; | ||
| display: flex; align-items: center; justify-content: center; | ||
| flex-shrink: 0; | ||
| } | ||
| .logo svg { width: 22px; height: 22px; fill: white; } | ||
| h1 { font-size: 22px; font-weight: 600; } | ||
| h1 span { display: block; font-size: 13px; color: var(--text-muted); font-weight: 400; margin-top: 2px; } | ||
| .version-list { display: flex; flex-direction: column; gap: 8px; } | ||
| .version-item { | ||
| display: flex; align-items: center; justify-content: space-between; | ||
| padding: 14px 16px; | ||
| background: var(--surface); | ||
| border: 1px solid var(--border); | ||
| border-radius: 10px; | ||
| text-decoration: none; | ||
| color: var(--text); | ||
| transition: border-color 0.15s, box-shadow 0.15s; | ||
| } | ||
| .version-item:hover { | ||
| border-color: var(--accent); | ||
| box-shadow: 0 0 0 1px var(--accent); | ||
| } | ||
| .version-name { font-weight: 500; font-size: 15px; } | ||
| .badge { | ||
| font-size: 11px; font-weight: 600; | ||
| padding: 3px 8px; border-radius: 20px; | ||
| text-transform: uppercase; letter-spacing: 0.5px; | ||
| } | ||
| .badge-latest { background: var(--green-bg); color: var(--green); } | ||
| .badge-dev { background: var(--yellow-bg); color: var(--yellow); } | ||
| .arrow { | ||
| color: var(--text-muted); | ||
| transition: transform 0.15s; | ||
| flex-shrink: 0; margin-left: 8px; | ||
| } | ||
| .version-item:hover .arrow { transform: translateX(3px); color: var(--accent); } | ||
| .version-left { display: flex; align-items: center; gap: 10px; } | ||
| </style> | ||
| </head> | ||
| <body> | ||
| <div class="container"> | ||
| <div class="header"> | ||
| <div class="logo"> | ||
| <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"> | ||
| <path d="M13.983 11.078h2.119a.186.186 0 0 0 .186-.186V9.006a.186.186 0 0 0-.186-.186h-2.119a.186.186 0 0 0-.187.186v1.886c0 .103.084.186.187.186m-2.954-5.43h2.118a.186.186 0 0 0 .187-.186V3.574a.186.186 0 0 0-.187-.186h-2.118a.186.186 0 0 0-.187.186v1.888c0 .103.083.186.187.186m0 5.43h2.118a.186.186 0 0 0 .187-.186V9.006a.186.186 0 0 0-.187-.186h-2.118a.186.186 0 0 0-.187.186v1.886c0 .103.083.186.187.186m-2.965 0h2.118a.186.186 0 0 0 .187-.186V9.006a.186.186 0 0 0-.187-.186H8.064a.186.186 0 0 0-.187.186v1.886c0 .103.084.186.187.186"/> | ||
| </svg> | ||
| </div> | ||
| <h1>Pipelines as Code<span>Documentation Versions</span></h1> | ||
| </div> | ||
| <div class="version-list"> | ||
| <a href="/${latest}/" class="version-item"> | ||
| <div class="version-left"> | ||
| <span class="version-name">${latest}</span> | ||
| <span class="badge badge-latest">latest</span> | ||
| </div> | ||
| <svg class="arrow" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 3l5 5-5 5"/></svg> | ||
| </a> | ||
| <a href="/nightly/" class="version-item"> | ||
| <div class="version-left"> | ||
| <span class="version-name">nightly</span> | ||
| <span class="badge badge-dev">development</span> | ||
| </div> | ||
| <svg class="arrow" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 3l5 5-5 5"/></svg> | ||
| </a> | ||
| EOF | ||
|
|
||
| for v in ${output}; do | ||
| [[ "${v}" == "${latest}" ]] && continue | ||
| cat <<ITEM >>${versiondir}/versions.html | ||
| <a href="/${v}/" class="version-item"> | ||
| <div class="version-left"> | ||
| <span class="version-name">${v}</span> | ||
| </div> | ||
| <svg class="arrow" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 3l5 5-5 5"/></svg> | ||
| </a> | ||
| ITEM | ||
| done | ||
|
|
||
| cat <<EOF >>${versiondir}/versions.html | ||
| </div> | ||
| </div> | ||
| </body> | ||
| </html> | ||
| EOF |
There was a problem hiding this comment.
Embedding a large block of HTML and CSS directly within a shell script using cat <<EOF makes the script very long and difficult to read, maintain, and debug. Any changes to the HTML structure or CSS styling require editing a multi-line string within a shell script, which is error-prone and lacks proper syntax highlighting or tooling support.
Consider moving this HTML/CSS content into a separate template file (e.g., versions.html.tmpl) and using a templating engine or a simpler sed command to inject dynamic values like ${latest} and loop through versions. This would significantly improve the maintainability and readability of the gendocs.sh script.
| # Copyright 2024 Chmouel Boudjnah <chmouel@chmouel.com> | ||
| set -eufo pipefail | ||
| dir=/var/www/docs | ||
| keeplast=10 |
There was a problem hiding this comment.
The value 10 is a magic number. It would be more maintainable to define this as a named constant at the top of the script, or make it configurable via an environment variable, to improve readability and make its purpose clear.
| keeplast=10 | |
| KEEPLAST_VERSIONS=10 |
| find "${target_dir}" -name '*.html' -type f -exec perl -0777 -i -pe ' | ||
| s{<select[^>]*handleVersion[^>]*>.*?</select>.*?<script[^>]*>.*?handleVersion.*?</script>} | ||
| {<a href="/versions.html" style="text-decoration:none;padding:4px 10px;border:1px solid \x23ccc;border-radius:4px;display:inline-block">Other Versions</a>}gs; |
There was a problem hiding this comment.
Using inline styles (style="text-decoration:none;padding:4px 10px;border:1px solid \x23ccc;border-radius:4px;display:inline-block") within the generated HTML is generally discouraged. It mixes presentation with structure, making the HTML harder to maintain and less flexible. Consider defining a CSS class for this styling and applying the class to the <a> tag instead.
| find "${target_dir}" -name '*.html' -type f -exec perl -0777 -i -pe ' | |
| s{<select[^>]*handleVersion[^>]*>.*?</select>.*?<script[^>]*>.*?handleVersion.*?</script>} | |
| {<a href="/versions.html" style="text-decoration:none;padding:4px 10px;border:1px solid \x23ccc;border-radius:4px;display:inline-block">Other Versions</a>}gs; | |
| {<a href="/versions.html" class="version-selector-link">Other Versions</a>}gs; |
Implemented a
versions.htmlpage to list all available documentationversions and added a static version selector link to replace the
deprecated dynamic dropdown. Incorporated legacy support for older Hugo
APIs and fixed broken image paths in configuration files to ensure
consistency across documentation releases.
see it live here https://docs.pipelinesascode.com/versions.html
📝 Description of the Change
🔗 Linked GitHub Issue
Fixes #
🧪 Testing Strategy
🤖 AI Assistance
AI assistance can be used for various tasks, such as code generation,
documentation, or testing.
Please indicate whether you have used AI assistance
for this PR and provide details if applicable.
Important
Slop will be simply rejected, if you are using AI assistance you need to make sure you
understand the code generated and that it meets the project's standards. you
need at least know how to run the code and deploy it (if needed). See
startpaac to make it easy
to deploy and test your code changes.
If the majority of the code in this PR was generated by an AI, please add a
Co-authored-bytrailer to your commit message.For example:
Co-authored-by: Claude noreply@anthropic.com
✅ Submitter Checklist
fix:,feat:) matches the "Type of Change" I selected above.make testandmake lintlocally to check for and fix anyissues. For an efficient workflow, I have considered installing
pre-commit and running
pre-commit installtoautomate these checks.