Merge pull request #908 from bhrutledge/866-docs-links

Author: webknjaz

source/tutorials/installing-packages.rst

@@ -189,7 +189,7 @@ This will create a new virtual environment in the ``tutorial_env`` subdirectory,
 and configure the current shell to use it as the default ``python`` environment.
 
 
-.. _`Creating and using Virtual Environments`:
+.. _Creating and using Virtual Environments:
 
 Creating Virtual Environments
 =============================

source/tutorials/packaging-projects.rst

@@ -77,14 +77,9 @@ Creating a test directory
 Creating pyproject.toml
 -----------------------
 
-:file:`pyproject.toml` is the file that tells build tools (like ``pip`` and
-``build``) what system you are using and what is required for building. The
-default if this file is missing is to assume a classic setuptools build system,
-but it is better to be explicit; if you have a :file:`pyproject.toml` file, you
-will be able to rely on ``wheel`` and other packages being present.
-
-This file should be ideal for most setuptools projects:
-
+:file:`pyproject.toml` tells build tools (like :ref:`pip` and :ref:`build`)
+what is required to build your project. This tutorial uses :ref:`setuptools`,
+so open :file:`pyproject.toml` and enter the following content:
 
 .. code-block:: toml
 
@@ -100,12 +95,13 @@ This file should be ideal for most setuptools projects:
 package. Listing something here will *only* make it available during the build,
 not after it is installed.
 
-``build-system.build-backend`` is technically optional, but you will get
-``setuptools.build_meta:__legacy__`` instead if you forget to include it, so
-always include it. If you were to use a different build system, such as
-:ref:`flit` or `poetry`_, those would go here, and the configuration details
-would be completely different than the setuptools configuration described
-below. See :pep:`517` and :pep:`518` for background and details.
+``build-system.build-backend`` is the name of Python object that will be used to
+perform the build. If you were to use a different build system, such as
+:ref:`flit` or :ref:`poetry`, those would go here, and the configuration details
+would be completely different than the :ref:`setuptools` configuration described
+below.
+
+See :pep:`517` and :pep:`518` for background and details.
 
 
 Configuring metadata
@@ -165,8 +161,9 @@ be required, but can be omitted with newer versions of setuptools and pip.
 
     There are a `variety of metadata and options
     <https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html>`_
-    supported here. This is in configparser format; do not place quotes around values.
-    This example package uses a relatively minimal set of metadata:
+    supported here. This is in :doc:`configparser <python:library/configparser>`
+    format; do not place quotes around values. This example package uses a
+    relatively minimal set of ``metadata``:
 
     - ``name`` is the *distribution name* of your package. This can be any name as
       long as it only contains letters, numbers, ``_`` , and ``-``. It also must not
@@ -198,7 +195,7 @@ be required, but can be omitted with newer versions of setuptools and pip.
       your package will work on. For a complete list of classifiers, see
       https://pypi.org/classifiers/.
 
-    In the options category, we have controls for setuptools itself:
+    In the ``options`` category, we have controls for setuptools itself:
 
     - ``package_dir`` is a mapping of package names and directories.
       An empty package name represents the "root package" --- the directory in
@@ -212,7 +209,7 @@ be required, but can be omitted with newer versions of setuptools and pip.
       to use. In this case, the list of packages will be ``example_pkg`` as
       that's the only package present.
     - ``python_requires`` gives the versions of Python supported by your
-      project. Installers like pip will look back though older versions of
+      project. Installers like :ref:`pip` will look back though older versions of
       packages until it finds one that has a matching Python version.
 
     There are many more than the ones mentioned here. See
@@ -303,7 +300,7 @@ be required, but can be omitted with newer versions of setuptools and pip.
       subpackages under ``package_dir``. In this case, the list of packages will
       be ``example_pkg`` as that's the only package present.
     - ``python_requires`` gives the versions of Python supported by your
-      project. Installers like pip will look back though older versions of
+      project. Installers like :ref:`pip` will look back though older versions of
       packages until it finds one that has a matching Python version.
 
     There are many more than the ones mentioned here. See
@@ -367,14 +364,14 @@ Including other files
 ---------------------
 
 The files listed above will be included automatically in your
-:term:`source distribution <Source Distribution (or "sdist")>`. If you want to control what goes in this
-explicitly, see :ref:`Using MANIFEST.in`.
+:term:`source distribution <Source Distribution (or "sdist")>`. If you want to
+control what goes in this explicitly, see :ref:`Using MANIFEST.in`.
 
 The final :term:`built distribution <Built Distribution>` will have the Python
 files in the discovered or listed Python packages. If you want to control what
 goes here, such as to add data files, see
-:std:doc:`Including Data Files <setuptools:userguide/datafiles>`
-from the :std:doc:`setuptools docs <setuptools:index>`.
+:doc:`Including Data Files <setuptools:userguide/datafiles>`
+from the :doc:`setuptools docs <setuptools:index>`.
 
 .. _generating archives:
 
@@ -385,7 +382,7 @@ The next step is to generate :term:`distribution packages <Distribution
 Package>` for the package. These are archives that are uploaded to the Python
 Package Index and can be installed by :ref:`pip`.
 
-Make sure you have the latest version of PyPA's ``build`` installed:
+Make sure you have the latest version of PyPA's :ref:`build` installed:
 
 .. tab:: Unix/macOS
 
@@ -445,14 +442,13 @@ Uploading the distribution archives
 
 Finally, it's time to upload your package to the Python Package Index!
 
-The first thing you'll need to do is register an account on Test PyPI, which
+The first thing you'll need to do is register an account on TestPyPI, which
 is a separate instance of the package index intended for testing and
 experimentation. It's great for things like this tutorial where we don't
 necessarily want to upload to the real index. To register an account, go to
 https://test.pypi.org/account/register/ and complete the steps on that page.
 You will also need to verify your email address before you're able to upload
-any packages.  For more details on Test PyPI, see
-:doc:`/guides/using-testpypi`.
+any packages.  For more details, see :doc:`/guides/using-testpypi`.
 
 To securely upload your project, you'll need a PyPI `API token`_. Create one at
 https://test.pypi.org/manage/account/#api-tokens, setting the "Scope" to "Entire
@@ -515,8 +511,8 @@ Installing your newly uploaded package
 --------------------------------------
 
 You can use :ref:`pip` to install your package and verify that it works.
-Create a new :ref:`virtualenv` (see :doc:`/tutorials/installing-packages` for
-detailed instructions) and install your package from TestPyPI:
+Create a :ref:`virtual environment <Creating and using Virtual Environments>`
+and install your package from TestPyPI:
 
 .. tab:: Unix/macOS
 
@@ -532,7 +528,7 @@ detailed instructions) and install your package from TestPyPI:
 
 Make sure to specify your username in the package name!
 
-pip should install the package from Test PyPI and the output should look
+pip should install the package from TestPyPI and the output should look
 something like this:
 
 .. code-block:: text
@@ -550,21 +546,21 @@ something like this:
    installing dependencies when using TestPyPI.
 
 You can test that it was installed correctly by importing the package.
-Run the Python interpreter (make sure you're still in your virtualenv):
+Make sure you're still in your virtual environment, then run Python:
 
 .. tab:: Unix/macOS
 
     .. code-block:: bash
 
-        python3 
+        python3
 
 .. tab:: Windows
 
     .. code-block:: bash
 
-        py 
+        py
 
-and from the interpreter shell import the package:
+and import the package:
 
 .. code-block:: python
 
@@ -583,7 +579,7 @@ Next steps
 
 Keep in mind that this tutorial showed you how to upload your package to Test
 PyPI, which isn't a permanent storage. The Test system occasionally deletes
-packages and accounts. It is best to use Test PyPI for testing and experiments
+packages and accounts. It is best to use TestPyPI for testing and experiments
 like this tutorial.
 
 When you are ready to upload a real package to the Python Package Index you can
@@ -607,8 +603,5 @@ some things you can do:
 * Read more about using :ref:`setuptools` to package libraries in
   :doc:`/guides/distributing-packages-using-setuptools`.
 * Read about :doc:`/guides/packaging-binary-extensions`.
-* Consider alternatives to :ref:`setuptools` such as :ref:`flit`, `hatch`_,
-  and `poetry`_.
-
-.. _hatch: https://github.com/ofek/hatch
-.. _poetry: https://python-poetry.org
+* Consider alternatives to :ref:`setuptools` such as :ref:`flit`, :ref:`hatch`,
+  and :ref:`poetry`.