Merge branch 'main' into use-python3.9

dukecat0 · web-flow · commit 0e6d3c4efd2b · 2021-08-26T21:32:51.000+08:00
diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
@@ -0,0 +1,47 @@
+name: Translation
+
+on:
+   workflow_run:
+     workflows:
+     - Test
+     branches:
+     - main
+     types:
+     - completed
+
+jobs:
+   build:
+     runs-on: ubuntu-latest
+
+     steps:
+       - name: Grab the repo src
+         uses: actions/checkout@v2
+
+       - name: Set up Python
+         uses: actions/setup-python@v2
+         with:
+           python-version: 3.9
+
+       - name: Install Python tooling
+         run: python -m pip install --upgrade nox virtualenv
+
+       - name: Generate a fresh POT file out of RST documents
+         run: python -m nox -s translation
+
+       - name: Commit the POT file to Git
+         run: |
+           git config --local user.email "github-actions[bot]@users.noreply.github.com"
+           git config --local user.name "github-actions[bot]"
+           git_hash=$(git rev-parse --short "${GITHUB_SHA}")
+           git commit -m "Update messages.pot as of version ${git_hash}" locales/messages.pot
+
+       - name: Check if any sources have changed since the last update
+         if: failure()
+         run: echo "There are no changes to the RST sources since the last update. Nothing to do."
+
+       - name: >-
+           Push the updated POT file back to
+           ${{ github.repository }}@${{ github.event.repository.default_branch }}
+           on GitHub
+         run: |
+           git push --atomic origin HEAD:${{ github.event.repository.default_branch }}
diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst
@@ -4,7 +4,7 @@ Deploying Python applications
 =============================
 
 :Page Status: Incomplete
-:Last Reviewed: 2014-11-11
+:Last Reviewed: 2021-8-24
 
 .. contents:: Contents
    :local:
@@ -83,9 +83,50 @@ Application bundles
 
   FIXME
 
-  - py2exe/py2app/PEX
   - wheels kinda/sorta
 
+Windows
+-------
+
+py2exe
+^^^^^^
+
+`py2exe <https://pypi.org/project/py2exe/>`__ is a distutils extension which
+allows to build standalone Windows executable programs (32-bit and 64-bit) 
+from Python scripts. Python versions included in the official development 
+cycle are supported (refers to `Status of Python branches`__). py2exe can
+build console executables and windows (GUI) executables. Building windows
+services, and DLL/EXE COM servers might work but it is not actively supported.
+The distutils extension is released under the MIT-licence and Mozilla 
+Public License 2.0.
+
+.. __: https://devguide.python.org/#status-of-python-branches
+
+macOS
+-----
+
+py2app
+^^^^^^
+
+`py2app <https://pypi.org/project/py2app/>`__ is a Python setuptools 
+command which will allow you to make standalone macOS application 
+bundles and plugins from Python scripts. Note that py2app MUST be used
+on macOS to build applications, it cannot create Mac applications on other
+platforms. py2app is released under the MIT-license.
+
+Unix (including Linux and macOS)
+-----------------------------------
+
+pex
+^^^
+
+`pex <https://pypi.org/project/pex/>`__ is  a library for generating .pex 
+(Python EXecutable) files which are executable Python environments in the 
+spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` 
+and makes the deployment of Python applications as simple as cp. pex files may 
+even include multiple platform-specific Python distributions, meaning that a 
+single pex file can be portable across Linux and macOS. pex is released under the
+Apache License 2.0.
 
 Configuration management
 ========================
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
@@ -34,8 +34,7 @@ cached copies of :term:`packages <Distribution Package>`:
    by downloading all the requirements for a project and then pointing pip at
    those downloaded files instead of going to PyPI.
 2. A variation on the above which pre-builds the installation files for
-   the requirements using `python -m pip wheel
-   <https://pip.readthedocs.io/en/latest/reference/pip_wheel.html>`_:
+   the requirements using :ref:`python -m pip wheel <pip:pip wheel>`:
 
    .. code-block:: bash
 
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
@@ -5,8 +5,10 @@ Installing pip/setuptools/wheel with Linux Package Managers
 ===========================================================
 
 :Page Status: Incomplete
-:Last Reviewed: 2015-09-17
+:Last Reviewed: 2021-07-26
 
+.. contents:: Contents
+  :local:
 
 This section covers how to install :ref:`pip`, :ref:`setuptools`, and
 :ref:`wheel` using Linux package managers.
@@ -31,33 +33,16 @@ versions.  When this is known, we will make note of it below.
 Fedora
 ~~~~~~
 
-* Fedora 21:
+.. code-block:: bash
 
-  * Python 2::
+  sudo dnf install python3-pip python3-wheel
 
-      sudo yum upgrade python-setuptools
-      sudo yum install python-pip python-wheel
-
-  * Python 3: ``sudo yum install python3 python3-wheel``
-
-* Fedora 22:
-
-  * Python 2::
-
-      sudo dnf upgrade python-setuptools
-      sudo dnf install python-pip python-wheel
-
-  * Python 3: ``sudo dnf install python3 python3-wheel``
-
-
-To get newer versions of pip, setuptools, and wheel for Python 2, you can enable
-the `PyPA Copr Repo <https://copr.fedoraproject.org/coprs/pypa/pypa/>`_ using
-the `Copr Repo instructions
-<https://fedorahosted.org/copr/wiki/HowToEnableRepo>`__, and then run::
-
-  sudo yum|dnf upgrade python-setuptools
-  sudo yum|dnf install python-pip python-wheel
+To learn more about Python in Fedora, please visit the `official Fedora docs`_,
+`Python Classroom`_ or `Fedora Loves Python`_. 
 
+.. _official Fedora docs: https://developer.fedoraproject.org/tech/languages/python/python-installation.html
+.. _Python Classroom: https://labs.fedoraproject.org/en/python-classroom/
+.. _Fedora Loves Python: https://fedoralovespython.org
 
 CentOS/RHEL
 ~~~~~~~~~~~
@@ -69,14 +54,12 @@ To install pip and wheel for the system Python, there are two options:
 
 1. Enable the `EPEL repository <https://fedoraproject.org/wiki/EPEL>`_ using
    `these instructions
-   <https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F>`__. On
-   EPEL 6 and EPEL7, you can install pip like so::
-
-     sudo yum install python-pip
+   <https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F>`__. 
+   On EPEL 7, you can install pip and wheel like so:
 
-   On EPEL 7 (but not EPEL 6), you can install wheel like so::
+   .. code-block:: bash
 
-     sudo yum install python-wheel
+     sudo dnf install python3-pip python3-wheel
 
    Since EPEL only offers extra, non-conflicting packages, EPEL does not offer
    setuptools, since it's in the core repository.
@@ -85,13 +68,17 @@ To install pip and wheel for the system Python, there are two options:
 2. Enable the `PyPA Copr Repo
    <https://copr.fedoraproject.org/coprs/pypa/pypa/>`_ using `these instructions
    <https://fedorahosted.org/copr/wiki/HowToEnableRepo>`__ [1]_. You can install
-   pip and wheel like so::
+   pip and wheel like so:
+
+   .. code-block:: bash
+
+     sudo dnf install python3-pip python3-wheel
 
-     sudo yum install python-pip python-wheel
+   To additionally upgrade setuptools, run:
 
-   To additionally upgrade setuptools, run::
+   .. code-block:: bash
 
-     sudo yum upgrade python-setuptools
+     sudo dnf upgrade python3-setuptools
 
 
 To install pip, wheel, and setuptools, in a parallel, non-system environment
@@ -113,37 +100,29 @@ To install pip, wheel, and setuptools, in a parallel, non-system environment
    Pythons, along with pip, setuptools, and wheel, which are kept fairly up to
    date.
 
-   For example, for Python 3.4 on CentOS7/RHEL7::
+   For example, for Python 3.4 on CentOS7/RHEL7:
+
+   .. code-block:: bash
 
      sudo yum install python34u python34u-wheel
 
 
 openSUSE
 ~~~~~~~~
 
-* Python 2::
-
-    sudo zypper install python-pip python-setuptools python-wheel
-
-
-* Python 3::
+  .. code-block:: bash
  
     sudo zypper install python3-pip python3-setuptools python3-wheel
 
-
 Debian/Ubuntu
 ~~~~~~~~~~~~~
 
+Firstly, update and refresh repository lists by running this command:
 
-* Python 2::
-
-    sudo apt install python-pip
-
-
-* Python 3::
-
-    sudo apt install python3-venv python3-pip
+.. code-block:: bash
 
+  sudo apt update
+  sudo apt install python3-venv python3-pip
 
 .. warning::
 
@@ -155,11 +134,7 @@ Debian/Ubuntu
 Arch Linux
 ~~~~~~~~~~
 
-* Python 2::
-
-    sudo pacman -S python2-pip
-
-* Python 3::
+  .. code-block:: bash
 
     sudo pacman -S python-pip
 
diff --git a/source/guides/using-testpypi.rst b/source/guides/using-testpypi.rst
@@ -13,18 +13,18 @@ Registering your account
 ------------------------
 
 Because TestPyPI has a separate database from the live PyPI, you'll need a
-separate user account for specifically for TestPyPI. Go to
+separate user account specifically for TestPyPI. Go to
 https://test.pypi.org/account/register/ to register your account.
 
-.. Note:: The database for TestPyPI may be periodically pruned, so it is not
+.. note:: The database for TestPyPI may be periodically pruned, so it is not
     unusual for user accounts to be deleted.
 
 
 Using TestPyPI with Twine
 -------------------------
 
 You can upload your distributions to TestPyPI using :ref:`twine` by specifying
-the ``--repository`` flag
+the ``--repository`` flag:
 
 .. code-block:: bash
 
@@ -38,8 +38,8 @@ your project to appear on the site.
 Using TestPyPI with pip
 -----------------------
 
-You can tell pip to download packages from TestPyPI instead of PyPI by
-specifying the ``--index-url`` flag
+You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI by
+specifying the ``--index-url`` flag:
 
 .. tab:: Unix/macOS
 
@@ -53,21 +53,21 @@ specifying the ``--index-url`` flag
 
         py -m pip install --index-url https://test.pypi.org/simple/ your-package
 
-If you want to allow pip to also pull other packages from PyPI you can
+If you want to allow pip to also download packages from PyPI, you can
 specify ``--extra-index-url`` to point to PyPI. This is useful when the package
 you're testing has dependencies:
 
 .. tab:: Unix/macOS
 
     .. code-block:: bash
 
-        python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package
+        python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package
 
 .. tab:: Windows
 
     .. code-block:: bat
 
-        py -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package
+        py -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package
 
 Setting up TestPyPI in :file:`.pypirc`
 --------------------------------------
diff --git a/source/key_projects.rst b/source/key_projects.rst
@@ -323,21 +323,6 @@ libraries in a package.
 Non-PyPA Projects
 #################
 
-.. _bento:
-
-bento
-=====
-
-`Docs <http://cournape.github.io/Bento/>`__ |
-`Issues <https://github.com/cournape/Bento/issues>`__ |
-`GitHub <https://github.com/cournape/Bento>`__ |
-`PyPI <https://pypi.org/project/bento>`__
-
-Bento is a packaging tool solution for Python software, targeted as an
-alternative to :ref:`distutils`, :ref:`setuptools`, etc....  Bento's
-philosophy is reproducibility, extensibility and simplicity (in that
-order).
-
 .. _buildout:
 
 buildout
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
@@ -298,8 +298,7 @@ Use pip for Installing
 
 :ref:`pip` is the recommended installer.  Below, we'll cover the most common
 usage scenarios. For more detail, see the `pip docs <https://pip.pypa.io>`_,
-which includes a complete `Reference Guide
-<https://pip.pypa.io/en/latest/reference/index.html>`_.
+which includes a complete :doc:`Reference Guide <pip:cli/index>`.
 
 
 Installing from PyPI
@@ -653,15 +652,15 @@ Install `setuptools extras`_.
 
         python3 -m pip install SomePackage[PDF]
         python3 -m pip install SomePackage[PDF]==3.0
-        python3 -m pip install -e .[PDF]==3.0  # editable project in current directory
+        python3 -m pip install -e .[PDF]  # editable project in current directory
 
 .. tab:: Windows
 
     .. code-block:: bat
 
         py -m pip install SomePackage[PDF]
         py -m pip install SomePackage[PDF]==3.0
-        py -m pip install -e .[PDF]==3.0  # editable project in current directory
+        py -m pip install -e .[PDF]  # editable project in current directory
 
 ----
 
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
@@ -7,7 +7,7 @@ to build the package, and how to upload it to the Python Package Index.
 
 .. tip::
 
-   If you have trouble running the commands in this tutoral, please copy the command
+   If you have trouble running the commands in this tutorial, please copy the command
    and its output, then `open an issue`_ on the `packaging-problems`_ repository on
    GitHub. We'll do our best to help you!
 
