Merge branch 'main' into update-linux-package-managers

Author: webknjaz

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/guides/distributing-packages-using-setuptools.rst

@@ -666,9 +666,9 @@ both installed and editable in project form.
 
 Assuming you're in the root of your project directory, then run:
 
-::
+.. code-block:: bash
 
- python -m pip install -e .
+   python -m pip install -e .
 
 
 Although somewhat cryptic, ``-e`` is short for ``--editable``, and ``.`` refers
@@ -698,7 +698,9 @@ Otherwise, the dependency will be fulfilled from PyPI, due to the installation o
 <pip:Requirements Files>` section in the pip docs.  For more on VCS installs,
 see the :ref:`VCS Support <pip:VCS Support>` section of the pip docs.
 
-Lastly, if you don't want to install any dependencies at all, you can run::
+Lastly, if you don't want to install any dependencies at all, you can run:
+
+.. code-block:: bash
 
    python -m pip install -e . --no-deps
 
@@ -880,9 +882,11 @@ distribution file(s) to upload.
   directive). **Before** trying to upload your distribution, you should check
   to see if your brief / long descriptions provided in :file:`setup.py` are
   valid.  You can do this by running :std:doc:`twine check <index>` on
-  your package files::
+  your package files:
+
+  .. code-block:: bash
 
-    twine check dist/*
+     twine check dist/*
 
 Create an account
 -----------------

source/guides/dropping-older-python-versions.rst

@@ -105,7 +105,9 @@ Within a Python source package (the zip or the tar-gz file you download) is a te
 This file is generated by Distutils or :ref:`setuptools` when it generates the source package. 
 The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. 
 
-You can see the contents of the generated file like this::
+You can see the contents of the generated file like this:
+
+.. code-block:: bash
 
     tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO
 

source/guides/index-mirrors-and-caches.rst

@@ -35,10 +35,12 @@ cached copies of :term:`packages <Distribution Package>`:
    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>`_::
+   <https://pip.readthedocs.io/en/latest/reference/pip_wheel.html>`_:
 
-    python -m pip wheel --wheel-dir=/tmp/wheelhouse SomeProject
-    python -m pip install --no-index --find-links=/tmp/wheelhouse SomeProject
+   .. code-block:: bash
+
+      python -m pip wheel --wheel-dir=/tmp/wheelhouse SomeProject
+      python -m pip install --no-index --find-links=/tmp/wheelhouse SomeProject
 
 
 Caching with devpi

source/guides/installing-stand-alone-command-line-tools.rst

@@ -1,53 +1,55 @@
 Installing stand alone command line tools
 =========================================
 
-Many packages have command line entry points. Examples of this type of application are
+Many packages provide command line applications. Examples of such packages are
 `mypy <https://github.com/python/mypy>`_,
 `flake8 <https://github.com/PyCQA/flake8>`_,
-:ref:`pipenv`,and
-`black <https://github.com/ambv/black>`_.
+`black <https://github.com/psf/black>`_, and
+:ref:`pipenv`.
 
-Usually you want to be able to access these from anywhere,
-but installing packages and their dependencies to the same global environment
-can cause version conflicts and break dependencies the operating system has
-on Python packages.
+Usually you want to be able to access these applications from anywhere on your
+system, but installing packages and their dependencies to the same global
+environment can cause version conflicts and break dependencies the operating
+system has on Python packages.
 
-:ref:`pipx` solves this by creating a virtual
-environment for each package, while also ensuring that package's applications
-are accessible through a directory that is on your ``$PATH``. This allows each
-package to be upgraded or uninstalled without causing conflicts with other
-packages, and allows you to safely run the program from anywhere.
+:ref:`pipx` solves this by creating a virtual environment for each package,
+while also ensuring that its applications are accessible through a directory
+that is on your ``$PATH``. This allows each package to be upgraded or
+uninstalled without causing conflicts with other packages, and allows you to
+safely run the applications from anywhere.
 
 .. note:: pipx only works with Python 3.6+.
 
-``pipx`` is installed with ``pip``:
+pipx is installed with pip:
 
 .. tab:: Unix/macOS
 
   .. code-block:: bash
 
       python3 -m pip install --user pipx
-
-      python3 -m pipx ensurepath  # ensures the path of the CLI application directory is on your $PATH
+      python3 -m pipx ensurepath
 
 .. tab:: Windows
 
   .. code-block:: bat
 
       py -m pip install --user pipx
-      
       py -m pipx ensurepath
 
-.. Note:: You may need to restart your terminal for the path updates to take effect.
+.. note::
+
+   ``ensurepath`` ensures that the application directory is on your ``$PATH``.
+   You may need to restart your terminal for this update to take effect.
 
-Now you can install packages with ``pipx install`` and access the package's entry point(s) from anywhere.
+Now you can install packages with ``pipx install`` and run the package's
+applications(s) from anywhere.
 
 .. code-block:: console
 
   $ pipx install PACKAGE
-  $ ENTRYPOINT_OF_PACKAGE [ARGS]
+  $ PACKAGE_APPLICATION [ARGS]
 
-For example
+For example:
 
 .. code-block:: console
 
@@ -67,7 +69,8 @@ For example
              (__)\       )\/       ||----w |
                  ||     ||
 
-To see a list of packages installed with pipx and which CLI applications are available, use ``pipx list``.
+To see a list of packages installed with pipx and which applications are
+available, use ``pipx list``:
 
 .. code-block:: console
 
@@ -87,14 +90,14 @@ To see a list of packages installed with pipx and which CLI applications are ava
       - nox
       - tox-to-nox
 
-To upgrade or uninstall the package
+To upgrade or uninstall a package:
 
 .. code-block:: bash
 
   pipx upgrade PACKAGE
   pipx uninstall PACKAGE
 
-``pipx`` can be upgraded or uninstalled with pip
+pipx can be upgraded or uninstalled with pip:
 
 .. tab:: Unix/macOS
 
@@ -109,25 +112,18 @@ To upgrade or uninstall the package
 
       py -m pip install -U pipx
       py -m pip uninstall pipx
-      
-``pipx`` also allows you to install and run the latest version of a cli tool
-in a temporary, ephemeral environment.
-
-.. code-block:: bash
-
-  pipx run PACKAGE [ARGS]
 
-For example
+pipx also allows you to install and run the latest version of an application
+in a temporary, ephemeral environment. For example:
 
 .. code-block:: bash
 
   pipx run cowsay moooo
 
-To see the full list of commands ``pipx`` offers, run
+To see the full list of commands pipx offers, run:
 
 .. code-block:: bash
 
   pipx --help
 
-You can learn more about ``pipx`` at its homepage,
-https://github.com/pypa/pipx.
+You can learn more about pipx at https://pypa.github.io/pipx/.

source/guides/making-a-pypi-friendly-readme.rst

@@ -122,9 +122,11 @@ You can check your README for markup errors before uploading as follows:
 2. Build the sdist and wheel for your project as described under
    :ref:`Packaging Your Project`.
 
-3. Run ``twine check`` on the sdist and wheel::
+3. Run ``twine check`` on the sdist and wheel:
 
-        twine check dist/*
+   .. code-block:: bash
+
+      twine check dist/*
 
    This command will report any problems rendering your README.  If your markup
    renders fine, the command will output ``Checking distribution FILENAME:

source/guides/using-manifest-in.rst

@@ -93,7 +93,9 @@ setuptools will automatically convert the slashes to the local platform's
 appropriate directory separator.
 
 Commands are processed in the order they appear in the :file:`MANIFEST.in`
-file.  For example, given the commands::
+file.  For example, given the commands:
+
+.. code-block:: bash
 
     graft tests
     global-exclude *.py[cod]

source/specifications/source-distribution-format.rst

@@ -20,6 +20,16 @@ specification.
 
 Source distributions are also known as *sdists* for short.
 
+Source trees
+============
+
+A *source tree* is a collection of files and directories -- like a version
+control system checkout -- which contains a :file:`pyproject.toml` file that
+can be use to build a source distribution from the contained files and
+directories. :pep:`517` and :pep:`518` specify what is required to meet the
+definition of what :file:`pyproject.toml` must contain for something to be
+deemed a source tree.
+
 Source distribution file name
 =============================
 

source/tutorials/installing-packages.rst

@@ -281,9 +281,9 @@ In both of the above cases, Windows users should _not_ use the
 :command:`source` command, but should rather run the :command:`activate`
 script directly from the command shell like so:
 
-::
+.. code-block:: bat
 
- <DIR>\Scripts\activate
+   <DIR>\Scripts\activate
 
 
 
@@ -618,10 +618,10 @@ create a helper application that presents the data in a :pep:`503` compliant
 index format, and use the ``--extra-index-url`` flag to direct pip to use
 that index.
 
-::
+.. code-block:: bash
 
- ./s3helper --port=7777
- python -m pip install --extra-index-url http://localhost:7777 SomeProject
+   ./s3helper --port=7777
+   python -m pip install --extra-index-url http://localhost:7777 SomeProject
 
 
 Installing Prereleases