-
Notifications
You must be signed in to change notification settings - Fork 132
docs: add atsphinx-mini18n
to build i18n site
#3966
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
Thanks for opening a Pull Request. If you want to perform a review write a comment saying: @ansys-reviewer-bot review |
Reviewer's GuideIntegrates the atsphinx-mini18n extension into the documentation build by updating the CI workflow to source translations and run a per-language HTML build, configuring Sphinx to enable and merge language-specific outputs, and adding the required dependency. Sequence Diagram for CI i18n Documentation Build StepssequenceDiagram
actor GHUser as GitHub User/Committer
participant GHA as GitHub Actions Workflow
participant MainRepo as Main Project Repository
participant TranslationsRepo as pymapdl-doc-translations Repository
participant SphinxBuild as Sphinx Build Process
participant Mini18n as atsphinx-mini18n
GHUser->>MainRepo: Push code changes
GHA->>MainRepo: Checkout main project code
GHA->>SphinxBuild: Run standard 'make html'
SphinxBuild-->>GHA: Original HTML output (e.g., English)
GHA->>TranslationsRepo: Checkout 'pymapdl-doc-translations'
GHA->>SphinxBuild: Run 'make mini18n-html'
SphinxBuild->>Mini18n: Initialize with translations from TranslationsRepo
Mini18n-->>SphinxBuild: Generates HTML for each language (e.g., doc/_build/mini18n-html/ja)
SphinxBuild-->>GHA: Language-specific HTML outputs
GHA->>GHA: Copy language-specific HTML (e.g., ja/) into main HTML build (doc/_build/html/ja)
GHA->>GHA: Remove intermediate 'mini18n-html' directory
GHA->>GHA: Deploy updated HTML to documentation site
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pull Request Overview
This PR integrates atsphinx-mini18n to enable building a multilingual HTML documentation site.
- Adds atsphinx-mini18n as a documentation dependency
- Configures Sphinx to use the mini18n builder, templates, and language settings
- Updates CI workflow to checkout translations and merge per-language outputs into the main docs
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
File | Description |
---|---|
pyproject.toml | Add atsphinx-mini18n==0.4.1 to documentation dependencies |
doc/source/conf.py | Import and configure atsphinx.mini18n , templates, and languages |
.github/workflows/doc-build.yml | Checkout translations repo and build/merge i18n HTML outputs |
Comments suppressed due to low confidence (1)
doc/source/conf.py:452
- For atsphinx-mini18n, the configuration key should be
mini18n_locale_dirs
rather thanlocale_dirs
to ensure the translation files are properly picked up by the mini18n builder.
locale_dirs = ["../../pymapdl-doc-translations/locale"]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @tkoyama010 - I've reviewed your changes - here's some feedback:
- Consider extracting the find/cp/rm commands in the CI workflow into a reusable script or action to improve readability and maintainability.
- Double-check that the relative locale_dirs path in conf.py resolves correctly inside the GitHub Actions runner, or use an explicit path to avoid potential build breakage.
- Parameterize mini18n_support_languages (e.g. via an environment variable or separate config file) so you don’t need to edit conf.py each time you add a new language.
Here's what I looked at during the review
- 🟢 General issues: all looks good
- 🟢 Security: all looks good
- 🟢 Testing: all looks good
- 🟢 Documentation: all looks good
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Co-authored-by: Copilot <[email protected]>
@@ -86,6 +86,7 @@ tests = [ | |||
] | |||
|
|||
doc = [ | |||
"atsphinx-mini18n==0.4.1", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I created #3967 because I found it inconvenient that this isn’t automatically formatted.
This looks awesome! Thank you a lot @tkoyama010 !! I need to check with the documentation team and I will come back to this. I will keep you posted! |
for more information, see https://pre-commit.ci
Description
Please provide a brief description of the changes made in this pull request.
This provides builders that generate html document per translated languages on to outdir.
https://atsphinx.github.io/mini18n/en/usage/configuration/#example-for-pydata-sphinx-theme
_.mp4
Issue linked
Please mention the issue number or describe the problem this pull request addresses.
pyvista/pyvista#7517
Close #3965
Checklist
draft
if it is not ready to be reviewed yet.feat: adding new MAPDL command
)Summary by Sourcery
Extend the GitHub Actions docs build to generate internationalized HTML site using atsphinx-mini18n and merge per-language outputs into the main HTML directory.
New Features:
CI:
Summary by Sourcery
Integrate atsphinx-mini18n to generate and merge internationalized HTML documentation for English and Japanese into the existing docs build pipeline.
New Features:
Enhancements:
Build:
CI:
Documentation: