Merge branch 'main' into fix-url-easy_install

Author: webknjaz

.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 }}

source/contribute.rst

@@ -11,6 +11,7 @@ including:
 * Reviewing new contributions
 * Revising existing content
 * Writing new content
+* Translate the guide
 
 Most of the work on the |PyPUG| takes place on the
 `project's GitHub repository`__. To get started, check out the list of
@@ -67,7 +68,54 @@ an agreed-upon interface for interoperability between packaging tools.
 :doc:`example specification-style document <specifications/core-metadata>`.
 
 
+Translations
+============
 
+We use `Weblate`_ to manage translations of this project.
+Please visit the `packaging.python.org`_ project on Weblate to contribute.
+
+If you are experiencing issues while you are working on translations,
+please open an issue on `Github`_.
+
+.. tip::
+
+   Any translations of this project should follow `reStructuredText syntax`_.
+
+.. _Weblate: https://weblate.org/
+.. _packaging.python.org: https://hosted.weblate.org/projects/pypa/packaging-python-org/
+.. _Github: https://github.com/pypa/packaging.python.org/issues
+.. _reStructuredText syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+Adding a language
+-----------------
+
+If your language is not listed on `packaging.python.org`_, click the button
+:guilabel:`Start new translation` at the bottom of the language list and add
+the language you want to translate.
+
+Following reStructuredText syntax
+---------------------------------
+
+If you are not familiar with reStructuredText (RST) syntax, please read `this guide`_
+before translating on Weblate.
+
+**Do not translate the text in reference directly**
+
+  When translating the text in reference, please do not translate them directly.
+
+  | Wrong: Translate the following text directly:
+
+  .. code-block:: rst
+
+      `some ref`_ -> `TRANSLATED TEXT HERE`_
+
+  | Right: Translate the following text with your own language and add the original reference:
+
+  .. code-block:: rst
+
+      `some ref`_ -> `TRANSLATED TEXT HERE <some ref>`_
+
+.. _this guide: https://docutils.sourceforge.io/docs/user/rst/quickref.html
 
 Building the guide locally
 ==========================
@@ -77,7 +125,9 @@ in order to test your changes. In order to build this guide locally, you'll
 need:
 
 1. `Nox <https://nox.readthedocs.io/en/latest/>`_. You can install or upgrade
-   nox using ``pip``::
+   nox using ``pip``:
+
+   .. code-block:: bash
 
       python -m pip install --user nox
 
@@ -88,19 +138,23 @@ need:
 .. _Hitchhiker's Guide to Python installation instructions:
     http://docs.python-guide.org/en/latest/starting/installation/
 
-To build the guide, run the following bash command in the source folder::
+To build the guide, run the following bash command in the source folder:
 
-  nox -s build
+.. code-block:: bash
+
+   nox -s build
 
 After the process has completed you can find the HTML output in the
 ``./build/html`` directory. You can open the ``index.html`` file to view the
 guide in web browser, but it's recommended to serve the guide using an HTTP
 server.
 
 You can build the guide and serve it via an HTTP server using the following
-command::
+command:
+
+.. code-block:: bash
 
-  nox -s preview
+   nox -s preview
 
 The guide will be browsable via http://localhost:8000.
 

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
 ========================

source/glossary.rst

@@ -42,9 +42,8 @@ Glossary
     Egg
 
         A :term:`Built Distribution` format introduced by :ref:`setuptools`,
-        which is being replaced by :term:`Wheel`.  For details, see `The
-        Internal Structure of Python Eggs
-        <https://setuptools.readthedocs.io/en/latest/deprecated/python_eggs.html>`_ and
+        which is being replaced by :term:`Wheel`.  For details, see `
+        :doc:`The Internal Structure of Python Eggs <setuptools:deprecated/python_eggs>` and
         `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_
 
     Extension Module

source/guides/analyzing-pypi-package-downloads.rst

@@ -272,13 +272,13 @@ number of download for a package with the command ``pypinfo package_name``.
 
 Install `pypinfo`_ using pip.
 
-::
+.. code-block:: bash
 
     python -m pip install pypinfo
 
 Usage:
 
-::
+.. code-block:: console
 
     $ pypinfo requests
     Served from cache: False