Merge branch 'main' into copy-edit-pipx

Author: bhrutledge

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