From 721d197b3ec2fa0e2c52ca2398ba59b79add9b76 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Wed, 11 Sep 2024 11:21:21 +0100 Subject: [PATCH] ENH - Update translations workflows (#1959) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Daniel McCloy Co-authored-by: gabalafou Co-authored-by: M Bussonnier --- .github/workflows/CI.yml | 12 +- .github/workflows/prerelease.yml | 2 +- .github/workflows/publish.yml | 4 - docs/community/setup.md | 25 +- docs/community/topics/i18n.rst | 250 ++++++++++++------ docs/community/topics/nox.md | 36 --- docs/user_guide/i18n.rst | 44 +-- noxfile.py | 239 ----------------- .../locale/ca/LC_MESSAGES/sphinx.po | 42 +-- .../locale/cs/LC_MESSAGES/sphinx.po | 39 ++- .../locale/en/LC_MESSAGES/sphinx.po | 34 +-- .../locale/es/LC_MESSAGES/sphinx.po | 46 ++-- .../locale/fr/LC_MESSAGES/sphinx.po | 42 +-- .../locale/it/LC_MESSAGES/sphinx.po | 44 +-- .../locale/ru/LC_MESSAGES/sphinx.po | 39 ++- src/pydata_sphinx_theme/locale/sphinx.pot | 36 +-- .../locale/zh/LC_MESSAGES/sphinx.po | 44 +-- tox.ini | 126 ++++++--- webpack.config.js | 10 +- 19 files changed, 488 insertions(+), 626 deletions(-) delete mode 100644 docs/community/topics/nox.md delete mode 100644 noxfile.py diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index a7da7541f..1b7226e43 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -74,15 +74,15 @@ jobs: - name: "Run tests ✅" shell: bash run: | - # this will compile the assets then run the tests + # this will compile the assets and translations then run the tests # check if there is a specific Sphinx version to test with - # example substitution: tox run -e compile,py39-sphinx61-tests + # example substitution: tox run -e compile-assets,i18n-compile,py39-sphinx61-tests if [ -n "${{matrix.sphinx-version}}" ]; then - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests + python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests # if not we use the default version - # example substitution: tox run -e compile,py39-tests + # example substitution: tox run -e compile-assets,i18n-compile,py39-tests else - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests + python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests fi - name: "Upload coverage data to GH artifacts 📤" if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev' @@ -108,7 +108,7 @@ jobs: graphviz: true - name: "Run accessibility tests with playwright 🎭" # build PST, build docs, then run a11y-tests - run: python -Im tox run -e py312-docs,a11y-tests + run: python -Im tox run -m a11y # Build our docs (PST) on major OSes and check for warnings build-site: diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml index f6e84b69b..41ba3736a 100644 --- a/.github/workflows/prerelease.yml +++ b/.github/workflows/prerelease.yml @@ -37,7 +37,7 @@ jobs: - name: "Run tests ✅ (no coverage)" run: | # this will compile the assets then run the tests - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov + python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV # If either the docs build or the tests resulted in an error, create an issue to note it diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index edfbfc440..a4f50f048 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -39,10 +39,6 @@ jobs: python-version: "3.9" pandoc: "False" - - name: "Install gettext for translations 🌐" - run: | - sudo apt-get install gettext - - name: "Build and inspect package 📦" uses: hynek/build-and-inspect-python-package@v2 id: baipp diff --git a/docs/community/setup.md b/docs/community/setup.md index 9e397bbcb..f14961070 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -7,9 +7,8 @@ If you are comfortable with and prefer a more manual setup refer to the [](topic ## Testing pre-release and nightly -You can test the alpha, beta -and release candidates of pydata sphinx theme on your your projects. To do so -simply install with pip using the `--pre` flag: +You can test the alpha, beta and release candidates of the PyData Sphinx theme on your projects. +To do so install with pip using the `--pre` flag: ```console $ pip install --pre pydata-sphinx-theme @@ -20,9 +19,9 @@ If an `alpha`, `beta` or `rc` is available, pip will install it. You can use the `--pre` flag in your project's continuous integration test suite to catch regressions or bugs before their release. -If you are even more adventurous pydata-sphinx-theme has nightly builds, you can try following the +If you are even more adventurous `pydata-sphinx-theme` has nightly builds, you can try following the instructions provided [on the scientific-python/upload-nightly-action -Readme](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci) +README](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci) on installing nightly wheels. Installing nightly wheels in your project's CI jobs is a great way to help theme developers catch bugs ahead of @@ -145,6 +144,14 @@ $ python -m http.server -d docs/_build/html/ This will print a local URL that you can open in a browser to explore the HTML files. +You can also serve the documentation with live-reload using the following command: + +```console +$ tox run -e docs-live +``` + +This command will build the documentation and watch for any changes to the `doc` folder and rebuild the documentation automatically. + ### Change content and re-build Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds. @@ -162,7 +169,7 @@ These are then built and bundled with the theme (e.g., `scss` is turned into `cs To compile the CSS/JS assets with `tox`, run the following command: ```console -$ tox run -e compile +$ tox run -e compile-assets ``` This will compile all assets and place them in the appropriate folder to be used with documentation builds. @@ -174,12 +181,14 @@ The `sphinx-theme-builder` will bundle these assets automatically when we make a ## Run a development server -You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. +You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that +changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. To run the development server with `tox`, run the following command: ```console -$ tox run -e docs-live +# note the -m flag vs. other commands in this guide +$ tox run -m docs-live-server ``` When working on the theme, making changes to any of these directories: diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 68a8d0da7..8c1a2afd6 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -1,150 +1,228 @@ Internationalization ==================== -.. warning:: +This section covers how to internationalize (I18n) and localize (L10n) the PyData Sphinx Theme. +For details on how to localize the configurable strings in your Sphinx project, see the +:ref:`User guide section on internationalization `. - This theme is still in the process of setting up internationalization. - Some of the text below may not yet be correct (for example, we do not yet have a ``locales/`` directory). - Follow these issues to track progress: +The PyData Sphinx Theme I18n/i10n workflows are based on `GNU Gettext `__ +and `pybabel `__ is used to keep the catalogs up to date. +Crowd-sourced localizations are managed on `Transifex `__. - - https://github.com/pydata/pydata-sphinx-theme/issues/1162 - - https://github.com/pydata/pydata-sphinx-theme/issues/257 +.. note:: + **Internationalization** (or I18n) is the process of making a program or application aware of and able to support multiple + languages. + + **Localization** (L10n) is the process of translating localized programs or applications into different languages while + ensuring that the translations are correct for some native language and cultural habits. + + The formal description of specific set of cultural habits for some country, together with all associated translations + targeted to the same native language, is called the *locale* for this language or country. + For more information about localization and internationalization see `GNU gettext concepts `__. + + +The general process for internationalizing and localizing the theme is as follows: + +#. :ref:`Mark strings in the theme as localizable `. +#. :ref:`Extract localizable strings ` to a message catalog template ``POT`` (``PO`` template file). +#. Generare a ``PO`` file from the ``POT`` file for :ref:`a new language (locale) you want to localize ` + (or :ref:`update existing localization files `). +#. :ref:`Compile the message catalogs ` to binary ``MO`` files. +#. :ref:`Localize the theme `. + +Localization files +------------------- + +There are three types of files used in the localization process: + +#. `PO files `__ ( Portable Object, also known as message catalogs) + associate each original, translatable string (defined in ``msgid``) of a given program with its translation in a + particular target language (defined in ``msgstr`` fields). A single PO file is dedicated to a single target language. +#. ``MO`` (Machine Object) files are a binary version of a PO file. +#. ``POT`` (Portable Object Template) files are similar to PO files, but with empty translations. + They are used as a template for new languages. + + +.. _adding-localizable-text: + +Marking strings as localizable +------------------------------ + +All natural language text in the theme's components and layouts must be marked as localizable so that they can be later translated (or localized) into other languages. +For example, if you add a button with the text **Next page**, you will need to mark this text as localizable. -Internationalization (I18N) and localization (L10N) is performed using `Gettext `__. +``HTML`` templates (located in the ``src/pydata_sphinx_theme/theme/`` directory). +To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as localizable in the corresponding -Types of files --------------- +For example, to mark the text **Next page** as localizable, you would write: -Gettext reads a program's source and extracts text that has been marked as translatable, known as "source strings. -Gettext uses three types of files: +.. code-block:: jinja -PO file (``.po``) - A `Portable Object (PO) file `__ is made up of many entries. - Each entry holds the relation between a source string and its translation. - ``msgid`` contains the **source string**, and ``msgstr`` contains the **translation**. - In a given PO file, all translations are expressed in a single target language. - PO files are also known as "message catalogs". + - Entries begin with comments, on lines starting with the character ``#``. - Comments are created and maintained by Gettext. - Comment lines starting with ``#:`` contain references to the program's source. - These references allow a human translator to find the source strings in their original context. - Comment lines starting with ``#,`` contain flags like ``python-format``, which indicates that the source string contains placeholders like ``%(copyright)s``. -POT file (``.pot``) - A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages. -MO file (``.mo``) - A Machine Object (MO) file is a binary version of a PO file. PO files are compiled to MO files, which are required by Gettext. +Any text that is marked in this way will be discoverable by ``pybabel`` and used to generate the localization files +(``PO`` files). -.. _adding-natural-language-text: +Once you've marked the text as localizable, complete the steps outlined in the :ref:`updating-localization-files` +section of this documentation. -Mark natural language text as translateable -------------------------------------------- +For more details on marking strings as localizable in jinja templates visit `the Jinja2 documentation `__. -All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated by humans. +.. tip:: + Remember to `manually escape variables `__ if needed. -Jinja2 provides a ``trans`` block and a ``_()`` function to mark text as translatable. -`Please refer to the Jinja2 documentation `__. -Remember to `manually escape `__ variables if needed. +Sometimes, it can help localizers to describe where a string comes from or whether it refers to a noun or verb, +particularly if it can be difficult to find in the theme, or if the string itself is not very self-descriptive (for example, very short strings). +If you immediately precede the string with a comment that starts with ``L10n:``, the comment will be added to the PO +file, and visible to localizers. For example: -Any text that is marked in this way will be discoverable by ``gettext`` and used to generate ``.po`` files (see below for information). -Once you've marked text as translateable, complete the steps for :ref:`changing-natural-language-text`. +.. code-block:: jinja -.. _changing-natural-language-text: + {# L10n: Navigation button at the bottom of the page #} + -Add or change natural language text +.. _updating-localization-files: + +Updating the localization files ----------------------------------- -These steps cover how to add or change text that has been marked as translateable. +When you add or change natural language text in the theme, you must update the message catalogs to include the new or +updated text. Follow these steps: -#. Edit the natural language text as desired. - Ensure that it is {ref}`marked as translateable `. +#. Edit the natural language text and ensure it is :ref:`marked as localizable `. -#. Generate/update the message catalog template (``POT`` file) with `the PyBabel extract command `__: +#. Extract the strings and update the localization files (``POT`` file): .. code-block:: bash - pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot -k '_ __ l_ lazy_gettext' + # note this will by default update all the localization files for all the supported locales + tox run -e i18n-extract - **To run this in ``.nox``**: ``nox -s translate -- extract``. +This will update the localization files with new information about the position and text of the language you have modified. -#. Update the message catalogs (``PO`` files) with `the PyBabel update command `__: +If you *only* change non-localizable text (like HTML markup), the ``extract`` command will only update the +positions (line numbers) of the localizable strings. +Updating positions is optional - the line numbers are to inform the human translator, not to perform the localization. +But it is best practice to keep the positions up to date. - .. code-block:: bash +If you change localizable strings, the above command will extract the new or updated strings to localization template +file (``POT``) and perform a fuzzy match between the new or updated strings and existing localizations in the +localization files. +If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry, this means that the +localization needs to be manually reviewed and possibly updated. +If after reviewing the localization you decide to keep the existing localization, you can remove the ``#, fuzzy`` +comment from the entry. +If there is no fuzzy match, it will add a new localization entry. +You can learn more about fuzzy entries in the `GNU gettext manual `__. - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx +.. _compiling-localization-files: - **To run this in ``.nox``**: ``nox -s translate -- update``. +Compiling the localization files +-------------------------------- +Gettext doesn't parse any text files, it reads a binary format for faster performance. To compile the latest PO files in +the repository run: -This will update these files with new information about the position and text of the language you have modified. +.. code-block:: bash -If you *only* change non-translatable text (like HTML markup), the `extract` and `update` commands will only update the positions (line numbers) of the translatable strings. Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. + tox run -e i18n-compile -If you change translatable strings, the `extract` command will extract the new or updated strings to the POT file, and the `update` command will try to fuzzy match the new or updated strings with existing translations in the PO files. -If there is a fuzzy match, a comment like `#, fuzzy` is added before the matched entry. -Otherwise, a new entry is added and needs to be translated. +You can also run the extract, update and compile commands in one go: +.. code-block:: bash -.. _translating-the-theme: + tox run -m i18n -Add translations to translateable text --------------------------------------- +This will update the localization files and compile them into binary ``MO`` files in a single step. +However, if there are fuzzy matches needing review, the compilation will fail, and you will need to review the +localizations manually. +Then compile the files again. -Once text has been marked as translateable, and ``PO`` files have been generated for it, we may add translations for new languages for the phrase. -This section covers how to do so. +.. _adding-new-language: -.. note:: +Adding a new language +---------------------- - These steps use the Spanish language as an example. - To translate the theme to another language, replace ``es`` with the language's two-letter lowercase `ISO 639-1 code `__. +The list of languages with existing (possibly incomplete) localizations is available in the +``src/pydata_sphinx_theme/locale`` directory. -#. If the language's code matches no sub-directory of the `pydata_sphinx_theme/locale `__ directory, initialize the language's message catalog (PO file) with `PyBabel init `__: +To add a new language, follow these steps: + +#. Identify the `ISO 639-1 code `__ for the new language. + +#. Generate a ``PO`` file based on ``POT`` file for this new language: .. code-block:: bash - pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx -l es + # for example, to add Quechua (ISO 639-1 code: qu) + tox -e i18n-new-locale -- qu - **To run this in ``.nox``**: ``nox -s translate -- init es`` +#. Update and compile the localization files as described in the :ref:`updating-localization-files` and + :ref:`compiling-localization-files` sections. Then commit the changes. +#. Localize the theme's into the newly added language (see :ref:`localizing-the-theme`). -#. Edit the language's message catalog at ``pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po``. For each source string introduced by the ``msgid`` keyword, add its translation after the ``msgstr`` keyword. +.. _localizing-the-theme: -#. Compile the message catalogs of every language. This creates or updates the MO files with `PyBabel compile `__: +Localizing the theme +--------------------- - .. code-block:: bash +We manage localizations on the `PyData Sphinx Theme project on Transifex `__. - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx +To contribute localization, follow these steps: - **To run this in ``.nox``**: ``nox -s translate -- compile``. +#. Sign up for a `Transifex account `__. +#. Join the `PyData Sphinx Theme project `__. +#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request + to add the new language following the steps outlined in :ref:`adding-new-language`. +#. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the + `Transifex documentation `__ for more information. -Translation tips ----------------- +Once you have completed your localization, the PyData Sphinx Theme maintainers will review and approve it. -Translate phrases, not words +Localization tips +----------------- + +Localize phrases, not words ```````````````````````````` -Full sentences and clauses must always be a single translatable string. -Otherwise, you can get ``next page`` translated as ``suivant page`` instead of as ``page suivante``, etc. +Full sentences and clauses must always be a single localizable string. +Otherwise, you can get ``next page`` localizated as ``suivant page`` instead of as ``page suivante``, etc. + +Dealing with variables and markup in localizations +`````````````````````````````````````````````````` + +A localizable string can be a combination of a fixed string and a variable, for example, ``Welcome to the Spanish version of the site`` +is a combination of the fixed parts ``Welcome to the`` and ``version of the site`` and the variable part ``Spanish``. + +.. code-block:: jinja + + {% trans language=language %} + Welcome to the {{ language }} version of the site + {% endtrans %} + +Binding the variable as ``language=language`` ensures the string can be properly localized, especially as the word order +may vary across locales. +The above string will be extracted as ``Welcome to the %(language) version of the site``. +The translator must use ``%(language)`` verbatim while localizing the theme. -Deal with variables and markup in translations -````````````````````````````````````````````````````````````` +When a block contains HTML with attributes, those which don't need to be localized should be passed as arguments. +This ensures strings won't need to be re-localized if those attributes change: -If a variable (like the ``edit_page_provider_name`` theme option) is used as part of a phrase, it must be included within the translatable string. -Otherwise, the word order in other languages can be incorrect. -In a Jinja template, simply surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}}`. -For example: ``{% trans provider=provider %}Edit on {{ provider }}{% endtrans %}`` -The translatable string is extracted as the Python format string ``Edit on %(provider)s``. -This is so that the same translatable string can be used in both Python code and Jinja templates. -It is the translator's responsibility to use ``%(provider)s`` verbatim in the translation. +.. code-block:: jinja -If a non-translatable word or token (like HTML markup) is used as part of a phrase, it must also be included within the translatable string. -For example: ``{% trans theme_version=theme_version|e %}Built with the PyData Sphinx Theme {{ theme_version }}.{% endtrans %}`` -It is the translator's responsibility to use the HTML markup verbatim in the translation. + {% trans url="https://pydata.org/" %} + Please visit the PyData website for more information. + {% endtrans %} References ---------- -I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basics technical tasks. You might like: +I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basic technical tasks. You might like: - `Internationalis(z)ing Code `__ by Computerphile on YouTube - `Falsehoods Programmers Believe About Language `__ by Ben Hamill diff --git a/docs/community/topics/nox.md b/docs/community/topics/nox.md deleted file mode 100644 index d62e5be57..000000000 --- a/docs/community/topics/nox.md +++ /dev/null @@ -1,36 +0,0 @@ -# Using `nox` - -Here are a few extra tips for using `nox`. - -:::{seealso} -The [`nox` command line documentation](https://nox.thea.codes/en/stable/usage.html) has a lot of helpful tips for extra functionality you can enable with the CLI. -::: - -## Re-install dependencies - -To re-execute the installation commands, use this pattern: - -```console -$ nox -s docs -- reinstall -``` - -Or to completely remove the environment generated by `nox` and start from scratch: - -```console -$ rm -rf .nox/docs -``` - -## Use `nox` with your global environment - -If you'd like to use `nox` with your **global** environment (the one from which you are calling `nox`), you can do so with: - -```console -$ nox --force-venv-backend none - -# alternatively: -$ nox --no-venv -``` - -Using `none` will re-use your current global environment. -See -[the nox documentation](https://nox.thea.codes/en/stable/usage.html#forcing-the-sessions-backend) for more details. diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 7d6756aef..db8c63664 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -1,22 +1,32 @@ +.. _user-guide-i18n: + Internationalization ==================== -This theme contains translatable strings. -There are two kinds of strings in this theme, with different steps to translate each. +This theme contains localizable (translatable) strings. +There are two kinds of strings in this theme, with different steps to translate each: + +* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. + To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-new-language` sections in the documentation. -**Built-in strings** are hard-coded in the theme's templates. -They will automatically be translated if the language is `supported `__. -To add another language, see :ref:`translating-the-theme`. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other + sections in :doc:`the user guide ` for examples of these configurable strings). + To translate these strings, see the :ref:`translating-configurable-strings` section in this page. -**Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples). -To translate these strings, see the section below. +.. _translating-configurable-strings: Translating configurable strings -------------------------------- -These instructions are for translating configurable strings (those that are customizable in ``html_theme_options``). +These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within +the ``conf.py`` file). + +These instructions assume that you store your translations in a ``locale`` directory under your documentation directory +and that you want to use ``messages`` as the name of the message catalog for these strings (you can change this name if +needed). -These instructions assume that you store your translations in a ``locale`` directory under your documentation directory, and that you want to use ``theme`` as the name of the message catalog for these strings. +Note you will also need to install `pybabel `__ to handle your +documentation translations. #. In your ``conf.py`` file: @@ -25,7 +35,7 @@ These instructions assume that you store your translations in a ``locale`` direc import os.path from sphinx.locale import get_translation - catalog = "theme" + catalog = "messages" _ = get_translation(catalog) html_theme_options = { @@ -53,17 +63,19 @@ These instructions assume that you store your translations in a ``locale`` direc app.add_message_catalog(catalog, locale_dir) -#. Extract the strings to translate: +#. Extract the strings to localize: .. code-block:: bash - pybabel extract . -o locale/theme.pot + pybabel extract . -o locale/messages.pot -#. Create a message catalog (changing the ``--locale`` option as desired): +#. Create a message catalog by specifying the `ISO 639-1 code `__ for the new language (using the ``--locale`` flag): .. code-block:: bash - pybabel init --input-file=locale/theme.pot --domain=theme --output-dir=locale --locale=fr + # for example, to add French (ISO 639-1 code: fr) + pybabel init --input-file=locale/messages.pot --domain=messages --output-dir=locale --locale=fr + #. Translate the message catalog by editing the file. @@ -71,4 +83,6 @@ These instructions assume that you store your translations in a ``locale`` direc .. code-block:: bash - pybabel compile --directory=locale --domain=theme + pybabel compile --directory=locale --domain=messages + +Done! Your configurable strings are now localized. diff --git a/noxfile.py b/noxfile.py deleted file mode 100644 index c4b2b0fdf..000000000 --- a/noxfile.py +++ /dev/null @@ -1,239 +0,0 @@ -"""Automatically build our documentation or run tests. - -Environments are re-used by default. -Re-install the environment from scratch: - - nox -s docs -- -r -""" - -import os -import shutil as sh -import tempfile -from pathlib import Path -from shlex import split -from textwrap import dedent - -import nox - -nox.options.reuse_existing_virtualenvs = True -ROOT = Path(__file__).parent - - -def _should_install(session: nox.Session) -> bool: - """Decide if we should install an environment or if it already exists. - - This speeds up the local install considerably because building the wheel - for this package takes some time. - - We assume that if `sphinx-build` is in the bin/ path, the environment is - installed. - - Parameter: - session: the current nox session - """ - if session.bin_paths is None: - session.log("Running with `--no-venv` so don't install anything...") - return False - bin_files = list(Path(session.bin).glob("*")) - sphinx_is_installed = any("sphinx-build" in ii.name for ii in bin_files) - force_reinstall = "reinstall" in session.posargs or "-r" in session.posargs - should_install = not sphinx_is_installed or force_reinstall - if should_install: - session.log("Installing fresh environment...") - else: - session.log("Skipping environment install...") - return should_install - - -@nox.session(reuse_venv=True) -def lint(session: nox.Session) -> None: - """Check the themes pre-commit before any other session.""" - session.install("pre-commit") - session.run("pre-commit", "run", "-a") - - -@nox.session() -def compile(session: nox.Session) -> None: - """Compile the theme's web assets with sphinx-theme-builder.""" - if _should_install(session): - session.install("-e", ".") - session.install("sphinx-theme-builder[cli]") - - session.run("stb", "compile") - - -@nox.session() -def docs(session: nox.Session) -> None: - """Build the documentation and place in docs/_build/html. Use --no-compile to skip compilation.""" - if _should_install(session): - session.install("-e", ".[doc]") - session.install("sphinx-theme-builder[cli]") - if "no-compile" not in session.posargs: - session.run("stb", "compile") - session.run( - "sphinx-build", - "-b=html", - "docs/", - "docs/_build/html", - "-v", - "-w", - "warnings.txt", - # suppress Py3.11's new "can't debug frozen modules" warning - env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"), - ) - session.run("python", "tests/utils/check_warnings.py") - - -@nox.session(name="docs-live") -def docs_live(session: nox.Session) -> None: - """Build the docs with a live server that re-loads as you make changes.""" - session.run(*split("pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx")) - if _should_install(session): - session.install("-e", ".[doc]") - # quick hack to get the patched version of stb - need to remove once a stb release is cut - session.install( - "sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b" - ) - session.run( - "stb", - "serve", - "docs", - "--open-browser", - r"--re-ignore=locale|api|_build|\.jupyterlite\.doit\.db", - # suppress Py3.11's new "can't debug frozen modules" warning - env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"), - ) - - -@nox.session() -def test(session: nox.Session) -> None: - """Run the test suite.""" - if _should_install(session): - session.install("-e", ".[test]") - session.run(*split("pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx")) - session.run("pytest", "-m", "not a11y", *session.posargs) - - -@nox.session() -def a11y(session: nox.Session) -> None: - """Run the accessibility test suite only.""" - if _should_install(session): - session.install("-e", ".[test, a11y]") - # Install the drivers that Playwright needs to control the browsers. - if os.environ.get("CI") or os.environ.get("GITPOD_WORKSPACE_ID"): - # CI and other cloud environments are potentially missing system - # dependencies, so we tell Playwright to also install the system - # dependencies - session.run("playwright", "install", "--with-deps") - else: - # But most dev environments have the needed system dependencies - session.run("playwright", "install") - # Build the docs so we can run accessibility tests against them. - session.run("nox", "-s", "docs") - # The next step would be to open a server to the docs for Playwright, but - # that is done in the test file, along with the accessibility checks. - session.run("pytest", "-m", "a11y", *session.posargs) - - -@nox.session(name="test-sphinx") -@nox.parametrize("sphinx", ["4", "5", "6"]) -def test_sphinx(session: nox.Session, sphinx: int) -> None: - """Run the test suite with a specific version of Sphinx.""" - if _should_install(session): - session.install("-e", ".[test]") - session.install(f"sphinx=={sphinx}") - session.run("pytest", *session.posargs) - - -@nox.session() -def translate(session: nox.Session) -> None: - """Translation commands. Available commands after `--` : extract, update, compile, init.""" - # get the command from posargs, default to "update" - pybabel_cmd, found = ("update", False) - for c in ["extract", "update", "compile", "init"]: - if c in session.posargs: - pybabel_cmd, found = (c, True) - - if found is False: - print( - "No translate command found. Use like: `nox -s translate -- COMMAND`." - "\ndefaulting to `update`" - "\nAvailable commands: extract, update, compile, init" - ) - - # get the language from parameters default to en. - # it can be deceiving but we don't have a table of accepted languages yet - lan = "en" if len(session.posargs) < 2 else session.posargs[-1] - - # get the path to the differnet local related pieces - locale_dir = str(ROOT / "src" / "pydata_sphinx_theme" / "locale") - babel_cfg = str(ROOT / "babel.cfg") - pot_file = str(locale_dir / "sphinx.pot") - - # install deps - session.install("Babel") - - # build the command from the parameters - cmd = ["pybabel", pybabel_cmd] - - if pybabel_cmd == "extract": - cmd += [ROOT, "-F", babel_cfg, "-o", pot_file, "-k", "_ __ l_ lazy_gettext"] - - elif pybabel_cmd == "update": - cmd += ["-i", pot_file, "-d", locale_dir, "-D", "sphinx"] - - elif pybabel_cmd == "compile": - cmd += ["-d", locale_dir, "-D", "sphinx"] - - elif pybabel_cmd == "init": - cmd += ["-i", pot_file, "-d", locale_dir, "-D", "sphinx", "-l", lan] - - session.run(cmd) - - -@nox.session() -def profile(session: nox.Session) -> None: - """Generate a profile chart with py-spy. The chart will be placed at profile.svg.""" - if _should_install(session): - session.install("-e", ".[test]") - session.install("py-spy") - - with tempfile.TemporaryDirectory() as tmpdir: - # Copy over our base test site to the temporary folder - path_base = Path("tests/sites/base/") - path_tmp = Path(tmpdir) / path_base - sh.copytree(path_base, path_tmp) - - # Add a bunch of extra files to increase the build length - index = path_tmp / "index.rst" - text = index.read_text() - text += dedent( - """ - .. toctree:: - :glob: - - many/* - """ - ) - index.write_text(text) - (path_tmp / "many").mkdir() - - # Create a bunch of empty pages to slow the build - n_extra_pages = 50 - for ii in range(n_extra_pages): - (path_tmp / "many" / f"{ii}.rst").write_text("Test\n====\n\nbody\n") - - if "-o" in session.posargs: - output = session.posargs[session.posargs.index("-o") + 1] - else: - output = "profile.svg" - - # Specify our output directory - path_tmp_out = path_tmp / "_build" - - # Profile the build - print(f"Profiling build with {n_extra_pages} pages with py-spy...") - session.run( - *f"py-spy record -o {output} -- sphinx-build {path_tmp} {path_tmp_out}".split() - ) - print(f"py-spy profiler output at this file: {output}") diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index 7c70e77c1..47f917c06 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -1,34 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# -# Translators: -# Cristhian Rivera, 2024 -# Oriol Abril-Pla , 2024 -# +# Catalan translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# msgid "" msgstr "" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "Fes clic per a desplegar" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Fes clic per a replegar" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Salta al contingut principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Torna a l'inici" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -42,18 +38,18 @@ msgstr "Error" msgid "Please activate JavaScript to enable the search functionality." msgstr "Activeu JavaScript per habilitar la funcionalitat de cerca." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Ruta de navegació" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Inici" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +125,7 @@ msgstr "" "Creada amb Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "clar/fosc" @@ -173,3 +169,7 @@ msgstr "Navegació del lloc" #~ msgid "Site Navigation" #~ msgstr "Navegació del lloc" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 91690218d..531811dbc 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -1,33 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. +# Czech translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. # -# Translators: -# Jan Breuer , 2024 msgid "" msgstr "" - -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Přejít k hlavnímu obsahu" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Zpět na začátek" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +38,18 @@ msgstr "Chyba" msgid "Please activate JavaScript to enable the search functionality." msgstr "Aktivujte prosím JavaScript, abyste umožnili vyhledávání." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Struktura" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Domů" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -128,7 +125,7 @@ msgstr "" "Vytvořeno pomocí Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "světlý/tmavý" @@ -152,7 +149,6 @@ msgid "Announcement" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html:3 -#, fuzzy msgid "Site navigation" msgstr "Navigace na stránce" @@ -171,3 +167,6 @@ msgstr "Navigace na stránce" #~ msgid "Twitter" #~ msgstr "Twitter" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index 093a8c841..4e0a2ac2b 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -1,31 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. +# English translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. # msgid "" msgstr "" - -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -39,17 +38,17 @@ msgstr "" msgid "Please activate JavaScript to enable the search functionality." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 @@ -124,7 +123,7 @@ msgid "" "%(sphinx_version)s." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "" @@ -166,3 +165,6 @@ msgstr "" #~ msgid "Site Navigation" #~ msgstr "" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "" + diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index 045c3d408..6f7616a65 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -1,35 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# -# Translators: -# Rambaud Pierrick , 2023 -# Cristhian Rivera, 2024 -# Felipe Moreno, 2024 -# +# Spanish translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# msgid "" msgstr "" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "Haga clic para ampliar" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Haga clic para colapsar" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Saltar al contenido principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Volver arriba" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,21 +36,20 @@ msgstr "Error" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:9 msgid "Please activate JavaScript to enable the search functionality." -msgstr "" -"Por favor, active JavaScript para habilitar la funcionalidad de búsqueda." +msgstr "Por favor, active JavaScript para habilitar la funcionalidad de búsqueda." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Miga de pan" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Inicio" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -131,7 +125,7 @@ msgstr "" "Creado usando Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "claro/oscuro" @@ -175,3 +169,7 @@ msgstr "Navegación del sitio" #~ msgid "Site Navigation" #~ msgstr "Navegación del sitio" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index edc7cd46f..ef498653a 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -1,34 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# -# Translators: -# Denis Bitouzé , 2024 -# Rambaud Pierrick , 2024 -# +# French translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# msgid "" msgstr "" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "Cliquez pour développer" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Cliquer pour réduire" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Passer au contenu principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Haut de page" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -42,18 +38,18 @@ msgstr "Erreur" msgid "Please activate JavaScript to enable the search functionality." msgstr "Veuillez activer le JavaScript pour que la recherche fonctionne." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Fil d'Ariane" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Accueil" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +125,7 @@ msgstr "" "Créé en utilisant Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "clair/sombre" @@ -173,3 +169,7 @@ msgstr "Navigation dans le site" #~ msgid "Site Navigation" #~ msgstr "Navigation du site" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index e3727f43b..e17f311c3 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -1,33 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# -# Translators: -# Stefano David, 2024 -# +# Italian translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# msgid "" msgstr "" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "Fai click per espandere" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Fai click per nascondere" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Passa ai contenuti principali" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Torna in alto" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -39,21 +36,20 @@ msgstr "Errore" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:9 msgid "Please activate JavaScript to enable the search functionality." -msgstr "" -"Per favore attiva JavaScpript per abilitare la funzionalità di ricerca." +msgstr "Per favore attiva JavaScpript per abilitare la funzionalità di ricerca." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Breadcrumb" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Pagina iniziale" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +125,7 @@ msgstr "" "Creato con Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "chiaro/scuro" @@ -173,3 +169,7 @@ msgstr "Navigazione del sito" #~ msgid "Site Navigation" #~ msgstr "Navigazione del sito" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index de1ba6d09..33c1c9097 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -1,33 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. +# Russian translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. # -# Translators: -# Rambaud Pierrick , 2023 msgid "" msgstr "" - -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Перейти к основному содержанию" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +38,18 @@ msgstr "Ошибка" msgid "Please activate JavaScript to enable the search functionality." msgstr "Активируйте JavaScript, чтобы включить функцию поиска." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Хлебная крошка" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Главная" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Копирайт %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Копирайт %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -128,7 +125,7 @@ msgstr "" "Создано с помощью Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "светлая/темная" @@ -152,7 +149,6 @@ msgid "Announcement" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html:3 -#, fuzzy msgid "Site navigation" msgstr "Навигация по сайту" @@ -171,3 +167,6 @@ msgstr "Навигация по сайту" #~ msgid "Twitter" #~ msgstr "Twitter" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Копирайт %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/sphinx.pot b/src/pydata_sphinx_theme/locale/sphinx.pot index 11c7f142d..9b4b240c3 100644 --- a/src/pydata_sphinx_theme/locale/sphinx.pot +++ b/src/pydata_sphinx_theme/locale/sphinx.pot @@ -1,41 +1,41 @@ -# Translations template for PROJECT. -# Copyright (C) 2024 ORGANIZATION -# This file is distributed under the same license as the PROJECT project. +# Translations template for pydata-sphinx-theme. +# Copyright (C) 2024 PyData developers +# This file is distributed under the same license as the pydata-sphinx-theme +# project. # FIRST AUTHOR , 2024. # -#, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" +"Project-Id-Version: pydata-sphinx-theme 0.15.4.dev0\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-05-10 18:43+0200\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.13.0\n" +"Generated-By: Babel 2.16.0\n" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -49,17 +49,17 @@ msgstr "" msgid "Please activate JavaScript to enable the search functionality." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 @@ -134,7 +134,7 @@ msgid "" "%(sphinx_version)s." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "" diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 45326b86d..25ed5b963 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -1,33 +1,30 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# -# Translators: -# 温欣, 2024 -# +# Chinese translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# msgid "" msgstr "" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "展开" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "收缩" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "跳转至主要内容" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "回到顶部" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +38,18 @@ msgstr "错误" msgid "Please activate JavaScript to enable the search functionality." msgstr "请启用 JavaScript 以启用搜索功能。" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Breadcrumb" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "初始页面" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -125,9 +122,10 @@ msgid "" "Created using Sphinx " "%(sphinx_version)s." msgstr "" -"使用 Sphinx %(sphinx_version)s创建." +"使用 Sphinx " +"%(sphinx_version)s创建." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "亮色/暗色" @@ -171,3 +169,7 @@ msgstr "网页导航" #~ msgid "Site Navigation" #~ msgstr "网址导航" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/tox.ini b/tox.ini index b675d5a9a..5e062a708 100644 --- a/tox.ini +++ b/tox.ini @@ -5,64 +5,72 @@ min_version = 4 # .github/actions/set-dev-env/action.yml (default Python version) env_list = lint, - compile, + compile-assets, + i18n-compile, py312-docs, py312-tests, a11y-tests -# convenience label for running tests with a given Python version, aimed at -# helping contributors run tests locally -# tox run -m tests -labels = - tests = compile, py312-tests - a11y = compile, py312-docs, a11y-tests +# convenience label for running tests with a given Python version, aimed at +# helping contributors run common tasks without needing to call all the steps +# For example to run the tests: tox run -m tests +labels = + tests = compile-assets, i18n-compile, py312-tests + a11y = compile-assets, i18n-compile, py312-docs, a11y-tests + i18n = i18n-extract, i18n-compile + live-server = compile-assets, i18n-compile, docs-live # general tox env configuration -# these can be run with any py3{9,12} version +# these can be run with any py3{9,12} version, for example: # tox run -e py39-lint [testenv] deps = lint: pre-commit - compile: sphinx-theme-builder[cli] + compile-assets: sphinx-theme-builder[cli] profile-docs: py-spy -extras = +extras = {docs-no-checks, docs-linkcheck, profile-docs}: doc -skip_install = +skip_install = lint: true # do not need to install to lint profile-docs: true # avoids issues with py-spy and setting the git repo - compile: false + compile-assets: false package = editable -commands = +commands = lint: pre-commit run -a - compile: stb compile - # can substitute the target directory + compile-assets: stb compile # bundle JavaScript and Sass + # can substitute the target directory with any other directory by calling: + # tox run -e docs-no-checks -- path/to/other/directory docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going # example tox run -e py39-profile-docs -- -o profile.svg -n 100 profile-docs: python ./tools/profile.py {posargs} -# tests can be ran with or without coverage (see examples below), -# it is recommended to run compile before running tests (see examples below), -# tox run -e compile,py39-tests -# if you want to skip the assets compilation step you can run the tests without -#`compile`, for example: -# tox run -e py39-tests +# tests can be ran with or without coverage (see examples below), +# it is recommended to run compile-assets before running tests +# i18n-compile MUST be run before running tests +# (see examples below), +# tox run -e compile-assets,i18n-compile,py39-tests +# if you want to skip the assets and translations compilation step you can run +# the tests without `compile-assets,i18n-compile`, for example: +# tox run -e py39-tests # run tests with a specific Sphinx version -# tox run -e compile,py39-sphinx61-tests +# tox run -e compile-assets,i18n-compile,py39-sphinx61-tests # run tests without coverage -# tox run -e compile,py39-tests-no-cov +# tox run -e compile-assets,i18n-compile,py39-tests-no-cov [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}] description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml" # need to ensure the package is installed in editable mode package = editable extras = test # install dependencies - defined in pyproject.toml -deps = +deps = coverage[toml] py39-sphinx61-tests: sphinx~=6.1.0 py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master -depends = compile -commands = +depends = + compile-assets, + i18n-compile +commands = py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs} py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs} @@ -73,16 +81,17 @@ commands = description = run accessibility tests with Playwright and axe-core base_python = py312 # keep in sync with tests.yml pass_env = GITHUB_ACTIONS # so we can check if this is run on GitHub Actions -extras = +extras = test a11y -depends = - compile, +depends = + compile-assets, + i18n-compile py312-docs allowlist_externals= playwright bash -commands = +commands = bash -c 'if [[ "{env:GITHUB_ACTIONS:}" == "true" ]]; then playwright install --with-deps; else playwright install; fi' pytest -m "a11y" {posargs} @@ -96,7 +105,7 @@ description = build the documentation and place in docs/_build/html set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 # keep this in sync across all docs environments extras = {[testenv:docs-no-checks]extras} -deps = +deps = py39-sphinx61-docs: sphinx~=6.1.0 commands = sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} @@ -116,17 +125,56 @@ commands = sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} python tests/utils/check_warnings.py - -[testenv:docs-live] +# build the docs with live-reload, if you are working on the docs only (no theme changes) the best option is to call +# tox run -e docs-live +# this will only watch the docs directory and rebuild the docs when changes are detected +# if you are working on the theme (HTML, jinja templates, JS, CSS) and the docs, you can call +# tox run -e docs-live-theme +[testenv:docs-live{,-theme}] description = "Build and serve the documentation with live-reload" -extras = +extras = dev - i18n package = editable -deps = +deps = sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b # suppress Py3.11's new "can't debug frozen modules" warning set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 -commands = - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx - stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db \ No newline at end of file +commands = + docs-live-theme: stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db + docs-live: sphinx-autobuild docs/ docs/_build/html --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db + +# extract translatable files into the POT file and update locale PO files +# tox run -e i18n-extract +# this will update all locales, to update a single locale you can +# pass the locale code, for example to update the Spanish locale only: +# tox run -e i18n-extract -- --locale=es +[testenv:i18n-extract] +description = "Extract translatable messages from the source code and update locale files" +extras = i18n +package = editable +allowlist_externals = bash +commands = + # explicitly pass this as a bash command to set PST_VERSION + bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \ + pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION" + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} + +# add a new locale for translations based on the catalog template +# the locale needs to be given in the format of the language code +# for example: `tox -e i18n-new-locale -- ss` +[testenv:i18n-new-locale] +description = "Create a new locale based on our catalog template" +extras = {[testenv:i18n-extract]extras} +package = editable +commands = + pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} + +# compile translation catalogs to binary MO files +# tox run -e i18n-compile +# tox run -e i18n-compile -- --use-fuzzy +[testenv:i18n-compile] +description = "Compile translation catalogs to binary MO files" +extras = {[testenv:i18n-extract]extras} +package = editable +commands = + pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx {posargs} diff --git a/webpack.config.js b/webpack.config.js index f5427e4c2..757d399f1 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -5,9 +5,8 @@ * * - Generates a `webpack-macros.html` file that defines macros used * to insert CSS / JS at various places in the main `layout.html` template. - * - Compiles our translation files into .mo files so they can be bundled with the theme * - Compiles our SCSS and JS and places them in the _static/ folder - * - Downloads and links FontAwesome and some JS libraries (Bootstrap, etc) + * - Vendors FontAwesome and some JS libraries (Bootstrap, etc) */ const { resolve } = require("path"); @@ -18,13 +17,6 @@ const TerserPlugin = require("terser-webpack-plugin"); const dedent = require("dedent"); const { Compilation } = require("webpack"); -/******************************************************************************* - * Compile our translation files - */ -const { exec } = require("child_process"); -const localePath = resolve(__dirname, "src/pydata_sphinx_theme/locale"); -exec(`pybabel compile -d ${localePath} -D sphinx`); - /******************************************************************************* * Paths for various assets (sources and destinations) */