Skip to content

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

Open
wants to merge 12 commits into
base: main
Choose a base branch
from

Conversation

tkoyama010
Copy link
Contributor

@tkoyama010 tkoyama010 commented May 28, 2025

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

@ansys-reviewer-bot
Copy link
Contributor

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

@ansys-reviewer-bot review

Copy link
Contributor

sourcery-ai bot commented May 28, 2025

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
Loading

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

@tkoyama010 tkoyama010 marked this pull request as ready for review May 28, 2025 20:34
@Copilot Copilot AI review requested due to automatic review settings May 28, 2025 20:34
@tkoyama010 tkoyama010 requested a review from a team as a code owner May 28, 2025 20:34
@tkoyama010 tkoyama010 requested review from germa89 and clatapie May 28, 2025 20:34
Copy link

@Copilot Copilot AI left a 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 than locale_dirs to ensure the translation files are properly picked up by the mini18n builder.
locale_dirs = ["../../pymapdl-doc-translations/locale"]

Copy link
Contributor

@sourcery-ai sourcery-ai bot left a 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

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]>
@@ -86,6 +86,7 @@ tests = [
]

doc = [
"atsphinx-mini18n==0.4.1",
Copy link
Contributor Author

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.

@germa89
Copy link
Collaborator

germa89 commented May 29, 2025

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants