feat: add multi-version documentation support#117
Conversation
- Add new workflow for building v2.0 (root) and v1.3 (/v1.3/) - Fix version_switcher.js regex to handle /v1.3/ paths - Update switcher.json with correct version URLs This enables deploying both documentation versions: - v2.0 (latest) from v2-odoo19-doc-refresh branch at / - v1.3 from stable branch at /v1.3/
- Disable csvlexer import in stable build (not in requirements) - Save version_switcher.js from stable before switching branches - Update old workflow to skip stable (now handled by multiversion) - Remove stable-specific code from old workflow (previews only)
- Remove ts-graphviz/setup-graphviz@v1, install graphviz via apt-get - Replace peaceiris/actions-gh-pages@v3 with git commands - Preserves preview deployments when deploying to cf-pages branch
- v1.3 (stable) now deployed to root / - v2.0 (preview) now deployed to /v2.0/ - Updated switcher.json with correct URLs
Git checkout was failing because conf.py was modified (csvlexer disabled). Now explicitly restores conf.py before branch switch.
Summary of ChangesHello @emjay0921, 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 system by implementing robust multi-version support. It introduces a new CI workflow to build and deploy distinct documentation versions (stable and preview) to different URL paths, alongside critical updates to the version switching logic and configuration. This change streamlines the management of documentation for various product versions and ensures compliance with GitHub Actions policies. Highlights
Changelog
Ignored Files
Activity
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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces support for multi-version documentation by adding a new CI workflow and updating the version switcher logic. The changes in switcher.json correctly configure the new stable (1.3) and preview (2.0) versions. The update to version_switcher.js fixes the regex to handle versioned paths like /v2.0/. I've suggested a small improvement to the JavaScript to make the code more concise. Overall, the changes look good and align with the goal of supporting multiple documentation versions.
| // This regex matches /previews/anything/ at the start | ||
| currentPath = currentPath.replace(/^\/previews\/[^\/]+\//, '/'); | ||
| // This regex matches /version-number/ patterns at the start | ||
| currentPath = currentPath.replace(/^\/[0-9.]+\//, '/'); | ||
| // This regex matches /v1.3/ or /1.3/ patterns at the start (with optional 'v' prefix) | ||
| currentPath = currentPath.replace(/^\/v?[0-9.]+\//, '/'); |
There was a problem hiding this comment.
For improved readability and slightly better performance, you can combine the two consecutive replace() calls into a single call. Using the | (OR) operator in the regular expression allows you to match either the preview path pattern or the version number pattern in one pass.
| // This regex matches /previews/anything/ at the start | |
| currentPath = currentPath.replace(/^\/previews\/[^\/]+\//, '/'); | |
| // This regex matches /version-number/ patterns at the start | |
| currentPath = currentPath.replace(/^\/[0-9.]+\//, '/'); | |
| // This regex matches /v1.3/ or /1.3/ patterns at the start (with optional 'v' prefix) | |
| currentPath = currentPath.replace(/^\/v?[0-9.]+\//, '/'); | |
| // This regex matches /previews/..., /v1.3/ or /1.3/ patterns at the start | |
| currentPath = currentPath.replace(/^\/(?:previews\/[^\/]+|v?[0-9.]+)\//, '/'); |
1 participant
Summary
build_deploy_multiversion.yml) for building and deploying multi-version documentationversion_switcher.jsregex to properly handle version pathsswitcher.jsonwith correct version URLs for productionHow it works
The new workflow builds two versions:
stablebranch -> deployed to root/v2-odoo19-doc-refreshbranch -> deployed to/v2.0/Changes
.github/workflows/build_deploy_multiversion.yml.github/workflows/build_deploy.ymldocs/_static/version_switcher.js/^\/v?[0-9.]+\//to handle version pathsdocs/_static/switcher.jsonGitHub Actions Compatibility
This workflow uses only GitHub-owned actions and native commands:
actions/checkout@v3- GitHub-ownedactions/setup-python@v4- GitHub-ownedgraphvizinstalled viaapt-get(replacests-graphviz/setup-graphviz@v1)peaceiris/actions-gh-pages@v3)This approach avoids the organization's policy that blocks third-party actions.
Test plan