Merge pull request #975 from meowmeowmeowcat/fix-broken-link

Use more intersphinx references & format some links

Author: webknjaz

README.rst

@@ -6,8 +6,8 @@ http://packaging.python.org
 The "Python Packaging User Guide" (PyPUG) aims to be the authoritative resource on
 how to package and install distributions in Python using current tools.
 
-To follow the development of Python packaging, see the `Python
-Packaging Authority <https://www.pypa.io>`_.
+To follow the development of Python packaging, see the :doc:`Python
+Packaging Authority <pypa:index>`.
 
 Code of Conduct
 ---------------

source/conf.py

@@ -398,14 +398,34 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
+    'boltons': ('https://boltons.readthedocs.io/en/latest/', None),
+    'build': ('https://pypa-build.readthedocs.io/en/stable/', None),
+    'cffi': ('https://cffi.readthedocs.io/en/latest/', None),
+    'conda': ('https://conda.io/en/latest/', None),
+    'devpi': ('https://devpi.net/docs/devpi/devpi/latest/+doc', None),
+    'dh-virtualenv': ('https://dh-virtualenv.readthedocs.io/en/latest/', None),
+    'distlib': ('https://distlib.readthedocs.io/en/latest/', None),
+    'flexx': ('https://flexx.readthedocs.io/en/latest/', None),
+    'nox': ('https://nox.thea.codes/en/latest/', None),
     'openstack': ('https://docs.openstack.org/glance/latest/', None),
+    'packaging': ('https://packaging.pypa.io/en/latest/', None),
+    'packaging.python.org': ('https://packaging.python.org/', None),
+    'pip': ('https://pip.pypa.io/en/latest/', None),
+    'pipenv': ('https://pipenv.pypa.io/en/latest/', None),
+    'piwheels': ('https://piwheels.readthedocs.io/en/latest/', None),
+    'pybind11': ('https://pybind11.readthedocs.io/en/stable/', None),
+    'pynsist': ('https://pynsist.readthedocs.io/en/latest/', None),
+    'pypa': ('https://www.pypa.io/en/latest/', None),
     'python': ('https://docs.python.org/3', None),
+    'python-guide': ('https://docs.python-guide.org', None),
     'python2': ('https://docs.python.org/2', None),
-    'pip': ('https://pip.pypa.io/en/latest/', None),
     'scipy': ('https://www.scipy.org', None),
     'setuptools': ('https://setuptools.readthedocs.io/en/latest/', None),
+    'spack': ('https://spack.readthedocs.io/en/latest/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
     'tox': ('https://tox.readthedocs.io/en/latest/', None),
     'twine': ('https://twine.readthedocs.io/en/stable/', None),
+    'virtualenv': ('https://virtualenv.pypa.io/en/stable/', None),
 }
 
 

source/contribute.rst

@@ -18,9 +18,9 @@ Most of the work on the |PyPUG| takes place on the
 `open issues`__ and `pull requests`__. If you're planning to write or edit
 the guide, please read the :ref:`style guide <contributing_style_guide>`.
 
-.. __: https://github.com/pypa/python-packaging-user-guide/
-.. __: https://github.com/pypa/python-packaging-user-guide/issues
-.. __: https://github.com/pypa/python-packaging-user-guide/pulls
+.. __: https://github.com/pypa/packaging.python.org/
+.. __: https://github.com/pypa/packaging.python.org/issues
+.. __: https://github.com/pypa/packaging.python.org/pulls
 
 By contributing to the |PyPUG|, you're expected to follow the PSF's
 `Code of Conduct`__.
@@ -124,19 +124,16 @@ Though not required to contribute, it may be useful to build this guide locally
 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
+1. :doc:`Nox <nox:index>`. You can install or upgrade
    nox using ``pip``:
 
    .. code-block:: bash
 
       python -m pip install --user nox
 
 2. Python 3.6. Our build scripts are designed to work with Python 3.6 only.
-   See the `Hitchhiker's Guide to Python installation instructions`_ to install
-   Python 3.6 on your operating system.
-
-.. _Hitchhiker's Guide to Python installation instructions:
-    http://docs.python-guide.org/en/latest/starting/installation/
+   See the :doc:`Hitchhiker's Guide to Python installation instructions <python-guide:starting/installation>`
+   to install Python 3.6 on your operating system.
 
 To build the guide, run the following bash command in the source folder:
 

source/discussions/deploying-python-applications.rst

@@ -73,7 +73,7 @@ directory, independent of any other Python installation on the computer.
 
 A big advantage of Pynsist is that the Windows packages can be built on Linux.
 There are several examples for different kinds of programs (console, GUI) in
-the `documentation <https://pynsist.readthedocs.io>`__. The tool is released
+the `documentation <pynsist:index>`. The tool is released
 under the MIT-licence.
 
 Application bundles

source/discussions/install-requires-vs-requirements.rst

@@ -88,4 +88,4 @@ installs them using ``python -m pip install -r``.
 ----
 
 .. [1] For more on "Abstract" vs "Concrete" requirements, see
-       https://caremad.io/2013/07/setup-vs-requirement/.
+       https://caremad.io/posts/2013/07/setup-vs-requirement/.

source/discussions/wheel-vs-egg.rst

@@ -39,7 +39,7 @@ Here's a breakdown of the important differences between :term:`Wheel` and :term:
   specification and the implementation that packaged it.
 
 * :term:`Wheel` is internally organized by `sysconfig path type
-  <http://docs.python.org/2/library/sysconfig.html#installation-paths>`_,
+  <https://docs.python.org/2/library/sysconfig.html#installation-paths>`_,
   therefore making it easier to convert to other formats.
 
 ----

source/glossary.rst

@@ -128,7 +128,7 @@ Glossary
 
         PyPA is a working group that maintains many of the relevant
         projects in Python packaging. They maintain a site at
-        https://www.pypa.io, host projects on `GitHub
+        :doc:`pypa.io <pypa:index>`, host projects on `GitHub
         <https://github.com/pypa>`_ and `Bitbucket
         <https://bitbucket.org/pypa>`_, and discuss issues on the
         `distutils-sig mailing list

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

@@ -53,7 +53,7 @@ In order to use `Google BigQuery`_ to query the `public PyPI download
 statistics dataset`_, you'll need a Google account and to enable the BigQuery
 API on a Google Cloud Platform project. You can run the up to 1TB of queries
 per month `using the BigQuery free tier without a credit card
-<https://cloud.google.com/blog/big-data/2017/01/how-to-run-a-terabyte-of-google-bigquery-queries-each-month-without-a-credit-card>`__
+<https://cloud.google.com/blog/products/data-analytics/query-without-a-credit-card-introducing-bigquery-sandbox>`__
 
 - Navigate to the `BigQuery web UI`_.
 - Create a new project.

source/guides/creating-and-discovering-plugins.rst

@@ -120,7 +120,7 @@ a list of packages to :func:`setup`'s ``packages`` argument instead of using
 Using package metadata
 ======================
 
-`Setuptools`_ provides :doc:`special support
+:doc:`Setuptools <setuptools:index>` provides :doc:`special support
 <setuptools:userguide/entry_point>` for plugins. By providing the
 ``entry_points`` argument to :func:`setup` in :file:`setup.py` plugins can
 register themselves for discovery.
@@ -171,5 +171,4 @@ Now the module of your choice can be imported by executing
    <python:library/importlib.metadata>`, most packaging tools other than setuptools
    provide support for defining entry points.
 
-.. _Setuptools: https://setuptools.readthedocs.io
 .. _backport: https://importlib-metadata.readthedocs.io/en/latest/

source/guides/distributing-packages-using-setuptools.rst

@@ -57,7 +57,7 @@ setup.py
 
 The most important file is :file:`setup.py` which exists at the root of your
 project directory. For an example, see the `setup.py
-<https://github.com/pypa/sampleproject/blob/master/setup.py>`_ in the `PyPA
+<https://github.com/pypa/sampleproject/blob/main/setup.py>`_ in the `PyPA
 sample project <https://github.com/pypa/sampleproject>`_.
 
 :file:`setup.py` serves two primary functions:
@@ -78,7 +78,7 @@ setup.cfg
 
 :file:`setup.cfg` is an ini file that contains option defaults for
 :file:`setup.py` commands.  For an example, see the `setup.cfg
-<https://github.com/pypa/sampleproject/blob/master/setup.cfg>`_ in the `PyPA
+<https://github.com/pypa/sampleproject/blob/main/setup.cfg>`_ in the `PyPA
 sample project <https://github.com/pypa/sampleproject>`_.
 
 
@@ -87,13 +87,13 @@ README.rst / README.md
 
 All projects should contain a readme file that covers the goal of the project.
 The most common format is `reStructuredText
-<http://docutils.sourceforge.net/rst.html>`_ with an "rst" extension, although
+<https://docutils.sourceforge.io/rst.html>`_ with an "rst" extension, although
 this is not a requirement; multiple variants of `Markdown
 <https://daringfireball.net/projects/markdown/>`_ are supported as well (look
 at ``setup()``'s :ref:`long_description_content_type <description>` argument).
 
 For an example, see `README.md
-<https://github.com/pypa/sampleproject/blob/master/README.md>`_ from the `PyPA
+<https://github.com/pypa/sampleproject/blob/main/README.md>`_ from the `PyPA
 sample project <https://github.com/pypa/sampleproject>`_.
 
 .. note:: Projects using :ref:`setuptools` 0.6.27+ have standard readme files
@@ -113,7 +113,7 @@ writing a :file:`MANIFEST.in` file, including a list of what's included by
 default, see ":ref:`Using MANIFEST.in`".
 
 For an example, see the `MANIFEST.in
-<https://github.com/pypa/sampleproject/blob/master/MANIFEST.in>`_ from the `PyPA
+<https://github.com/pypa/sampleproject/blob/main/MANIFEST.in>`_ from the `PyPA
 sample project <https://github.com/pypa/sampleproject>`_.
 
 .. note:: :file:`MANIFEST.in` does not affect binary distributions such as wheels.
@@ -128,7 +128,7 @@ If you're unsure which license to choose, you can use resources such as
 `GitHub's Choose a License <https://choosealicense.com/>`_ or consult a lawyer.
 
 For an example, see the `LICENSE.txt
-<https://github.com/pypa/sampleproject/blob/master/LICENSE.txt>`_ from the `PyPA
+<https://github.com/pypa/sampleproject/blob/main/LICENSE.txt>`_ from the `PyPA
 sample project <https://github.com/pypa/sampleproject>`_.
 
 <your package>
@@ -139,7 +139,7 @@ Python modules and packages under a single top-level package that has the same
 :ref:`name <setup() name>` as your project, or something very close.
 
 For an example, see the `sample
-<https://github.com/pypa/sampleproject/tree/master/src/sample>`_ package that's
+<https://github.com/pypa/sampleproject/tree/main/src/sample>`_ package that's
 included in the `PyPA sample project <https://github.com/pypa/sampleproject>`_.
 
 
@@ -154,7 +154,7 @@ specific details of your project are defined.
 
 The most relevant arguments are explained below. Most of the snippets given are
 taken from the `setup.py
-<https://github.com/pypa/sampleproject/blob/master/setup.py>`_ contained in the
+<https://github.com/pypa/sampleproject/blob/main/setup.py>`_ contained in the
 `PyPA sample project <https://github.com/pypa/sampleproject>`_.
 
 
@@ -237,7 +237,7 @@ A `content type
 can be specified with the ``long_description_content_type`` argument, which can
 be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, corresponding
 to no formatting, `reStructuredText (reST)
-<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names>`_,
+<https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names>`_,
 and the Github-flavored Markdown dialect of `Markdown
 <https://daringfireball.net/projects/markdown/>`_ respectively.
 
@@ -476,8 +476,8 @@ and it is interpreted relative to the installation prefix
 Each file name in ``files`` is interpreted relative to the :file:`setup.py`
 script at the top of the project source distribution.
 
-For more information see the distutils section on `Installing Additional Files
-<http://docs.python.org/3/distutils/setupscript.html#installing-additional-files>`_.
+For more information see the distutils section on :ref:`Installing Additional Files
+<python:distutils-additional-files>`.
 
 .. note::
 
@@ -490,8 +490,8 @@ For more information see the distutils section on `Installing Additional Files
 ``scripts``
 ~~~~~~~~~~~
 
-Although ``setup()`` supports a `scripts
-<http://docs.python.org/3/distutils/setupscript.html#installing-scripts>`_
+Although ``setup()`` supports a :ref:`scripts
+<python:distutils-installing-scripts>`
 keyword for pointing to pre-made scripts to install, the recommended approach to
 achieve cross-platform compatibility is to use :ref:`console_scripts` entry
 points (see below).
@@ -576,7 +576,7 @@ Semantic versioning (preferred)
 *******************************
 
 For new projects, the recommended versioning scheme is based on `Semantic Versioning
-<http://semver.org>`_, but adopts a different approach to handling pre-releases and
+<https://semver.org/>`_, but adopts a different approach to handling pre-releases and
 build metadata.
 
 The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE numbering scheme,
@@ -592,7 +592,7 @@ Adopting this approach as a project author allows users to make use of :pep:`"co
 a matching MAJOR version.
 
 Python projects adopting semantic versioning should abide by clauses 1-8 of the
-`Semantic Versioning 2.0.0 specification <http://semver.org>`_.
+`Semantic Versioning 2.0.0 specification <https://semver.org/>`_.
 
 Date based versioning
 *********************