Updates to commands.rst (#126)

* Updates to commands.rst

* Adittoanl typo

* Versions in "Merging translations into another branch"

* Manually updated versions

Author: StanFromIreland

docs/commands.rst

@@ -1,45 +1,49 @@
-============================================
-Commands for maintaining language repository
-============================================
+==============================================
+Commands for maintaining a language repository
+==============================================
 
-This document contains instructions to guide you on managing your language repository, hence helping you to translate
-Python's documentation to your language.
+This document contains instructions to guide you on managing your language
+repository, hence helping you translate Python's documentation to your language.
 
-These commands are written as in Linux Shell, and should work in Windows Subsystem Linux (WSL), but feel free to use the
-same logic in other languages e.g. Python.
+These commands are written in Linux Shell, and should work in Windows Subsystem
+Linux (WSL), but feel free to use the same logic in other languages e.g. Python.
 
-Note: Where you see ``${LANGCODE}`` in the commands below, replace it with your language code (e.g. 'uk', 'pt_BR') or
-set that variable (e.g. ``LANGCODE=pt_BR``) before running the commands.
+.. note::
+   Where you see ``${LANGCODE}`` in the commands below, replace it with your
+   language code (e.g. 'uk', 'pt_BR') or set the variable
+   (e.g. ``LANGCODE=pt_BR``) before running the commands.
 
 
 Clone CPython repository
 ------------------------
 
-It is necessary to have a local clone of CPython's source code repository in order to update translation files and to
-build translated documentation.
+It is necessary to have a local clone of `CPython's source code repository <https://github.com/python/cpython>`_
+in order to update translation files and to build translated documentation.
 
 From inside your language repository, run:
 
 .. code-block:: shell
 
-   BRANCH=3.12
+   BRANCH=|py_new|
    git clone --depth 1 https://github.com/python/cpython --branch $BRANCH
 
-``--depth 1`` do a shallow clone, which avoid downloading all the 800 MB of data from CPython's repository.
+Use ``--depth 1`` to shallow clone, which avoids downloading all the 800 MB of data
+from CPython's repository.
 
-Optionally, you could also add ``--no-single-branch`` to git clone command which would make all branches available,
-allowing to switch between one branch and another. But there is no need if you are working in the translation of a
-single branch.
+Optionally, you could also add ``--no-single-branch`` to ``git clone`` command which
+would make all branches available, allowing to switch between one branch and
+another. But this is not needed if you are working on the translation of a single branch.
 
 
 Install requirements
 --------------------
 
-Creating virtual environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating a virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Optionally, create a virtual environment (short: venv) to keep all Python package installations in it, then activate
-this venv to make sure commands are run from it:
+Optionally, create a `virtual environment <https://docs.python.org/3/library/venv.html>`_
+(short: *venv*) to keep all Python package installations in it, then activate
+this venv to ensure commands are run from it:
 
 .. code-block:: shell
 
@@ -49,14 +53,15 @@ this venv to make sure commands are run from it:
 Install Python packages
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Update pip and then install the Python requirements:
+Update pip and then install the required packages:
 
 .. code-block:: shell
 
    python -m pip install --upgrade pip
    python -m pip install sphinx-intl>=2.1.0 pomerge powrap sphinx-lint
 
-Alternatively, put all Python packages inside a requirements.txt file and install it using pip's ``-r`` flag.
+Alternatively, put all Python packages inside a requirements.txt file and install
+it using pip's ``-r`` flag.
 
 Transifex CLI tool
 ^^^^^^^^^^^^^^^^^^
@@ -69,37 +74,42 @@ Install the Transifex CLI client, required to interact with Transifex:
    curl -s -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh
    cd ../..
 
-Note: the above statements cause ``tx`` binary to be downloaded into .venv/bin directory. Feel free to install this
-tool wherever you want, but preferably in a directory already in the PATH so that issuing  ``tx`` works without its
-full path.
-
+.. note::
+   The above commands result in the ``tx`` binary being downloaded into the ``.venv/bin`` directory.
+   Feel free to install this tool wherever you want, but preferably in a
+   directory already in the PATH so that ``tx`` works without its full path.
 
 Updating the translations
 -------------------------
 
-For language teams that coordinate translation efforts in Transifex, updating translation means pulling the translation
-strings.
+For language teams that coordinate translation efforts on Transifex, updating
+translation means pulling the translation strings.
 
-Recommended: Before pulling translations, consider updating the .tx/config to have an up-to-date mapping of
-project/resources. For this, it is required to generate the documentation's pot files (template of po files),
-so start with the pot. Alternatively, you can skip it and pull translations, but new translation resources in Transifex
-could be not mapped, hence wouldn't be pulled.
+.. admonition:: Recommendation
+   Before pulling translations, consider updating the .tx/config to
+   have an up-to-date mapping of project/resources. For this, it is required to
+   generate the documentation's pot files (template of po files), so start
+   with the pot. Alternatively, you can skip it and pull translations, but new
+   translation resources in Transifex could be not mapped, and hence wouldn't be pulled.
+
+.. _generate-pot::
 
 Generating pot files
 ^^^^^^^^^^^^^^^^^^^^
 
-Let's use Sphinx's gettext builder for generating pot files:
+Sphinx's gettext builder can be used for generating pot files:
 
 .. code-block:: shell
 
    make -C cpython/Doc/ ALLSPHINXOPTS='-E -b gettext -D gettext_compact=0 -d build/.doctrees . locales/pot' build
 
-Now, there should be a cpython/Doc/locales/pot/ containing all the pot files.
+There should now be a ``cpython/Doc/locales/pot/`` directory containing all of the
+pot files.
 
-Generating .tx/config file
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Generating a .tx/config file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Having the pot files, make use of sphinx-intl to generate the .tx/config:
+Once you have the pot files, make use of sphinx-intl to generate the .tx/config:
 
 .. code-block:: shell
 
@@ -110,11 +120,13 @@ Having the pot files, make use of sphinx-intl to generate the .tx/config:
        --transifex-project-name=python-newest \
        --locale-dir . --pot-dir pot
 
-This step should take some time to finish. Once it is done, there should be a cpython/Doc/locales/.tx/config containing
-the list of resources based on the pot files previously generated.
+This step should take some time to finish. Once it is complete, there should be
+a ``cpython/Doc/locales/.tx/config`` file containing a list of resources based
+on the previously :ref:`generated pot files <generate-pot>`.
 
-As a final touch, we copy the .tx/config into the language repository making proper tweaks so one can download
-translations from Transifex or upload local translation changes, all this from repository's root directory:
+As a final touch, we copy the ``.tx/config`` to the language repository making
+proper tweaks so one can download translations from Transifex or upload local
+translation changes, all this from repository's root directory:
 
 .. code-block:: shell
 
@@ -127,18 +139,18 @@ translations from Transifex or upload local translation changes, all this from r
    sed -i .tx/config \
        -e "s|^xfile_filter  = ./<lang>/LC_MESSAGES/|trans.${LANGCODE}  = |;"
 
-Remapping translation and Transifex resources is done.
+Remapping translation and Transifex resources is complete.
 
-Pulling the translations
-^^^^^^^^^^^^^^^^^^^^^^^^
+Pulling translations
+^^^^^^^^^^^^^^^^^^^^
 
-Finally, let's download translations from Transifex using Transifex CLI tool:
+To download translations from Transifex using Transifex CLI tool:
 
 .. code-block:: shell
 
    tx pull -l ${LANGCODE} -t -f
 
-Command explanations:
+Argument explanations:
 
 * ``-l ${LANGCODE}`` – specify the language code so that tx doesn't pull all languages.
 * ``-t`` – specify that we want translations
@@ -147,43 +159,50 @@ Command explanations:
 Wrapping the translation files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-After pulling, it is highly recommended to use powrap in the po files to keep a better look:
+After pulling, it is highly recommended to use `powrap <https://pypi.org/project/powrap/>`_
+on the po files to make them look better:
 
 .. code-block:: shell
 
    powrap --quiet *.po **/*.po
 
-Alternatively, you can use ``--modified`` flag to save time and apply only to changed files.
+Alternatively, you can use ``--modified`` flag to save time and apply only to
+changed files.
 
 
 Commit and push translation changes
 -----------------------------------
 
-The following commands are recommended for committing and pushing your translations to the your language repository.
+The following commands are recommended for committing and pushing your
+translations to your language repository.
 
 .. code-block:: shell
 
    git diff -I'^"POT-Creation-Date: ' --numstat *.po **/*.po | cut -f3 | xargs -r git add
    git add $(git ls-files -o --exclude-standard *.po **/*.po) .tx/config
    git diff-index --quiet HEAD || { git commit -m "Update translations" && git push; }
 
-It is not recommended to simply "git add" (stage) all PO files because this would also staged and commit the translation
-files that have only irrelevant changes in their POT-Creation-Date header field (i.e. date when the PO was updated against
-the POT).
+It is not recommended to simply ``git add`` (stage) all PO files because this would
+also stage (and then commit) the translation files that have only irrelevant
+changes in their ``POT-Creation-Date`` header field (i.e. date when the PO was
+updated against the POT).
 
-The first command first git-add modified tracked files that does **not** exclusively match changes in POT-Creation-Date
-header, hence relevant changes are included.
+The first command first git-add modified tracked files that does **not**
+exclusively match changes in POT-Creation-Date header, hence relevant changes
+are included.
 
-The second command will git-add untracked po files that may have been newly created on the latest 'tx pull' run. It also
-adds .tx/config file.
+The second command will git-add untracked po files that may have been newly
+created on the latest 'tx pull' run. It also adds .tx/config file.
 
-The last command will only commit and push if any file was git-added in the above commands.
+The last command will only commit and push if any file was git-added in the
+above commands.
 
 
 Build translated documentation
 ------------------------------
 
-Useful for testing the translations, spotting syntax errors and viewing the result of your contribution.
+Useful for testing the translations, spotting syntax errors and viewing the
+result of your contribution.
 
 To build translated documentation, run:
 
@@ -193,11 +212,13 @@ To build translated documentation, run:
    make -C cpython/Doc venv
    make -C cpython/Doc SPHINXOPTS="--keep-going -D gettext_compact=0 -D language=${LANGCODE}" html
 
-The first command copies the translation files (.po) into cpython's locale_dir, which is required for it to be recognized.
+The first command copies the translation files (.po) into cpython's locale_dir,
+which is required for it to be recognized.
 
-Then create CPython's virtual environment using the Makefile from CPython's Doc directory:
+The second command creates a pre-configured virtual environment using the
+Makefile from CPython's Doc directory.
 
-Finally, build using the Makefile from CPython's Doc directory. Here is an explanation of the arguments used:
+Finally, build using the Makefile. Here is an explanation of the arguments used:
 
 * ``-C cpython/Doc`` – changes the current directory to run the make command
 * ``SPHINXOPTS`` – this variable should contain any CLI modifier command you want to pass
@@ -208,23 +229,24 @@ Finally, build using the Makefile from CPython's Doc directory. Here is an expla
 
 
 Viewing the documentation in a web browser
------------------------------------------
+------------------------------------------
 
-Just build translated documentation and then open in the browser, no secrets. See below a one-line command to use your
-default web browser to open the index.html:
+Just build translated documentation and then open in a browser, no secrets.
+See below a one-line command to use your default web browser to open the index.html:
 
 .. code-block:: shell
 
     python -c "import os, webbrowser; webbrowser.open('file://cpython/Doc/build/html/index.html')"
 
-Notice how index.html could be replaced with any page, e.g. 'library/os.html'.
+Notice ``index.html`` can be replaced with any file, e.g. ``'library/os.html'``.
 
 
 Linting the translation files
 -----------------------------
 
-``sphinx-lint`` is great to spot translation errors that will didn't spot e.g. trailing whitespace in the string, reST
-directive not properly surrounded with whitespace, etc. It's highly recommended.
+``sphinx-lint`` is great to spot translation errors that will didn't spot e.g.
+trailing whitespace in the string, reST directive not properly surrounded with
+whitespace, etc. It's highly recommended.
 
 .. code-block:: shell
 
@@ -234,20 +256,21 @@ directive not properly surrounded with whitespace, etc. It's highly recommended.
 Merging translations into another branch
 ----------------------------------------
 
-This is useful when you want to replicate a translation from the CPython branch currently being translated to another
-older branch. E.g. 3.12 is currently being translated, but 3.11 has that same string and could make use of the
-translation contributed.
+This is useful when you want to replicate a translation from the CPython branch
+currently being translated to another older branch. E.g. |py_new| is currently being
+translated, but |py_last| has that same string and could make use of the contributed
+translations.
 
 .. code-block:: shell
 
    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-   TARGET_BRANCH=3.11
+   TARGET_BRANCH=|py_last|
    pomerge --from-files *.po **/*.po
    git checkout ${TARGET_BRANCH}
    pomerge --to-files *.po **/*.po
 
-After the above command, the translation from the current branch were applied to the previous branch "3.11". Now, let's
-make sure lines are wrapped:
+After the above command, the translation from the current branch were applied to
+the previous branch |py_last|. Now, one can verify lines are wrapped:
 
 .. code-block:: shell
 

docs/conf.py

@@ -23,3 +23,14 @@
 
 html_theme = 'furo'
 html_static_path = ['_static']
+
+# ----------------------------------------------------------------------------
+
+# Python versions
+newest = '3.13'
+previous = '3.12'
+
+rst_prolog = f"""
+.. |py_new| replace:: {newest}
+.. |py_last| replace:: {previous}
+"""