docs: add `atsphinx-mini18n` to build i18n site #3966

tkoyama010 · 2025-05-28T20:31:43Z

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

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:

Add i18n documentation build step using the atsphinx-mini18n Sphinx builder.

CI:

Checkout the pymapdl-doc-translations repository to source translation files.
Run the mini18n-html build, copy each language’s HTML output into the main docs build, and remove the intermediate directory.

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:

Add i18n HTML documentation build step using atsphinx-mini18n
Include a language selection dropdown in the documentation navbar

Enhancements:

Merge per-language HTML outputs into the main documentation build
Configure Sphinx to support multiple languages with locale directories and templates

Build:

Add atsphinx-mini18n==0.4.1 to project dependencies

CI:

Checkout the pymapdl-doc-translations repository and run the mini18n-html build in GitHub Actions

Documentation:

Enable the atsphinx-mini18n extension and set mini18n options in Sphinx conf.py

for more information, see https://pre-commit.ci

ansys-reviewer-bot · 2025-05-28T20:31:46Z

Thanks for opening a Pull Request. If you want to perform a review write a comment saying:

@ansys-reviewer-bot review

sourcery-ai · 2025-05-28T20:31:48Z

Reviewer's Guide

Integrates 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 Steps

sequenceDiagram
    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

Change	Details	Files
Extend CI workflow to generate and merge per-language HTML docs	Checkout the pymapdl-doc-translations repository Run `make mini18n-html` to build translated docs Copy each language directory into the main HTML build Remove the intermediate mini18n build directory	`.github/workflows/doc-build.yml`
Enable and configure atsphinx.mini18n extension in Sphinx	Add `atsphinx.mini18n` to the `extensions` list Extend `templates_path` to include mini18n templates Insert a language selector snippet in the navbar Define `mini18n_default_language`, `mini18n_support_languages`, and `locale_dirs`	`doc/source/conf.py`
Add atsphinx-mini18n dependency to project configuration	Include `atsphinx-mini18n==0.4.1` in the `doc` dependencies section	`pyproject.toml`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

Copilot

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 than locale_dirs to ensure the translation files are properly picked up by the mini18n builder.

locale_dirs = ["../../pymapdl-doc-translations/locale"]

pyproject.toml

.github/workflows/doc-build.yml

sourcery-ai

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

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{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]>

tkoyama010 · 2025-05-28T20:42:53Z

pyproject.toml

@@ -86,6 +86,7 @@ tests = [
 ]

 doc = [
+  "atsphinx-mini18n==0.4.1",


I created #3967 because I found it inconvenient that this isn’t automatically formatted.

germa89 · 2025-05-29T09:14:29Z

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

pyproject.toml

tkoyama010 and others added 7 commits May 29, 2025 05:01

Add atsphinx-mini18n to build i18n site

6ca3f0f

Update conf.py

3983d6d

ci: auto fixes from pre-commit.com hooks.

e694032

for more information, see https://pre-commit.ci

Update pyproject.toml

0c7d8ff

ci: auto fixes from pre-commit.com hooks.

4b57ad5

for more information, see https://pre-commit.ci

Update conf.py

6526b1e

ci: auto fixes from pre-commit.com hooks.

97261ee

for more information, see https://pre-commit.ci

tkoyama010 marked this pull request as ready for review May 28, 2025 20:34

Copilot AI review requested due to automatic review settings May 28, 2025 20:34

tkoyama010 requested a review from a team as a code owner May 28, 2025 20:34

tkoyama010 requested review from germa89 and clatapie May 28, 2025 20:34

Copilot AI reviewed May 28, 2025

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

.github/workflows/doc-build.yml Show resolved Hide resolved

sourcery-ai bot reviewed May 28, 2025

View reviewed changes

Update pyproject.toml

bc3417b

Co-authored-by: Copilot <[email protected]>

tkoyama010 commented May 28, 2025

View reviewed changes

tkoyama010 and others added 2 commits May 30, 2025 21:42

Merge branch 'main' into docs/i18n

8cb10a2

ci: auto fixes from pre-commit.com hooks.

e55fade

for more information, see https://pre-commit.ci

tkoyama010 commented Jun 2, 2025

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

pyproject.toml Outdated Show resolved Hide resolved

tkoyama010 added 2 commits June 3, 2025 07:22

Apply suggestions from code review

dbaefff

Merge branch 'main' into docs/i18n

3a41375

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add `atsphinx-mini18n` to build i18n site #3966

docs: add `atsphinx-mini18n` to build i18n site #3966

tkoyama010 commented May 28, 2025 •

edited

Loading

Uh oh!

ansys-reviewer-bot bot commented May 28, 2025

Uh oh!

sourcery-ai bot commented May 28, 2025 •

edited

Loading

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

sourcery-ai bot left a comment

Uh oh!

tkoyama010 May 28, 2025

Uh oh!

germa89 commented May 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

docs: add atsphinx-mini18n to build i18n site #3966

Are you sure you want to change the base?

docs: add atsphinx-mini18n to build i18n site #3966

Conversation

tkoyama010 commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue linked

Checklist

Summary by Sourcery

Summary by Sourcery

Uh oh!

ansys-reviewer-bot bot commented May 28, 2025

Uh oh!

sourcery-ai bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

Sequence Diagram for CI i18n Documentation Build Steps

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

tkoyama010 May 28, 2025

Choose a reason for hiding this comment

Uh oh!

germa89 commented May 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

docs: add `atsphinx-mini18n` to build i18n site #3966

docs: add `atsphinx-mini18n` to build i18n site #3966

tkoyama010 commented May 28, 2025 •

edited

Loading

sourcery-ai bot commented May 28, 2025 •

edited

Loading