Set the default RST role in Sphinx to 'any'

webknjaz · webknjaz · commit 1ee61aa915c1 · 2020-08-11T13:00:40.000+02:00
This change allows to autolink refs with anonymous roles
to anything linkable.
diff --git a/source/conf.py b/source/conf.py
@@ -99,8 +99,8 @@
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#
-# default_role = None
+# Ref: python-attrs/attrs#571
+default_role = 'any'  # makes single backticks autofind targets
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #
diff --git a/source/discussions/pip-vs-easy-install.rst b/source/discussions/pip-vs-easy-install.rst
@@ -21,45 +21,45 @@ environments.
 
 Here's a breakdown of the important differences between pip and easy_install now:
 
-+------------------------------+----------------------------------+-------------------------------+
-|                              | **pip**                          | **easy_install**              |
-+------------------------------+----------------------------------+-------------------------------+
-|Installs from :term:`Wheels   |Yes                               |No                             |
-|<Wheel>`                      |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|Uninstall Packages            |Yes (``pip uninstall``)           |No                             |
-+------------------------------+----------------------------------+-------------------------------+
-|Dependency Overrides          |Yes (:ref:`Requirements Files     |No                             |
-|                              |<pip:Requirements Files>`)        |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|List Installed Packages       |Yes (``pip list`` and ``pip       |No                             |
-|                              |freeze``)                         |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|:pep:`438`                    |Yes                               |No                             |
-|Support                       |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|Installation format           |'Flat' packages with `egg-info`   | Encapsulated Egg format       |
-|                              |metadata.                         |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|sys.path modification         |No                                |Yes                            |
-|                              |                                  |                               |
-|                              |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|Installs from :term:`Eggs     |No                                |Yes                            |
-|<Egg>`                        |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|`pylauncher support`_         |No                                |Yes [1]_                       |
-|                              |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|:ref:`Multi-version Installs` |No                                |Yes                            |
-|                              |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|Exclude scripts during install|No                                |Yes                            |
-|                              |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
-|per project index             |Only in virtualenv                |Yes, via setup.cfg             |
-|                              |                                  |                               |
-+------------------------------+----------------------------------+-------------------------------+
++------------------------------+--------------------------------------+-------------------------------+
+|                              | **pip**                              | **easy_install**              |
++------------------------------+--------------------------------------+-------------------------------+
+|Installs from :term:`Wheels   |Yes                                   |No                             |
+|<Wheel>`                      |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|Uninstall Packages            |Yes (``pip uninstall``)               |No                             |
++------------------------------+--------------------------------------+-------------------------------+
+|Dependency Overrides          |Yes (:ref:`Requirements Files         |No                             |
+|                              |<pip:Requirements Files>`)            |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|List Installed Packages       |Yes (``pip list`` and ``pip           |No                             |
+|                              |freeze``)                             |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|:pep:`438`                    |Yes                                   |No                             |
+|Support                       |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|Installation format           |'Flat' packages with :file:`egg-info` | Encapsulated Egg format       |
+|                              |metadata.                             |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|sys.path modification         |No                                    |Yes                            |
+|                              |                                      |                               |
+|                              |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|Installs from :term:`Eggs     |No                                    |Yes                            |
+|<Egg>`                        |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|`pylauncher support`_         |No                                    |Yes [1]_                       |
+|                              |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|:ref:`Multi-version Installs` |No                                    |Yes                            |
+|                              |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|Exclude scripts during install|No                                    |Yes                            |
+|                              |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
+|per project index             |Only in virtualenv                    |Yes, via setup.cfg             |
+|                              |                                      |                               |
++------------------------------+--------------------------------------+-------------------------------+
 
 ----
 
diff --git a/source/glossary.rst b/source/glossary.rst
@@ -121,8 +121,8 @@ Glossary
 
     Pure Module
 
-        A :term:`module` written in Python and contained in a single `.py` file (and
-        possibly associated `.pyc` and/or `.pyo` files).
+        A :term:`module` written in Python and contained in a single ``.py`` file (and
+        possibly associated ``.pyc`` and/or ``.pyo`` files).
 
 
     Python Packaging Authority (PyPA)
@@ -147,7 +147,7 @@ Glossary
 
         `pypi.org <https://pypi.org>`_ is the domain name for the
         :term:`Python Package Index (PyPI)`. It replaced the legacy index
-        domain name, `pypi.python.org`, in 2017. It is powered by
+        domain name, ``pypi.python.org``, in 2017. It is powered by
         :ref:`warehouse`.
 
     pyproject.toml
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -815,10 +815,10 @@ To build the wheel:
  python setup.py bdist_wheel
 
 
-`bdist_wheel` will detect that the code is pure Python, and build a wheel that's
-named such that it's usable on any Python installation with the same major
-version (Python 2 or Python 3) as the version you used to build the wheel.  For
-details on the naming of wheel files, see :pep:`425`.
+``bdist_wheel`` will detect that the code is pure Python, and build a wheel
+that's named such that it's usable on any Python installation with the same
+major version (Python 2 or Python 3) as the version you used to build the
+wheel.  For details on the naming of wheel files, see :pep:`425`.
 
 If your code supports both Python 2 and 3, but with different code (e.g., you
 use `"2to3" <https://docs.python.org/2/library/2to3.html>`_) you can run
@@ -842,9 +842,9 @@ To build the wheel:
  python setup.py bdist_wheel
 
 
-`bdist_wheel` will detect that the code is not pure Python, and build a wheel
-that's named such that it's only usable on the platform that it was built
-on. For details on the naming of wheel files, see :pep:`425`.
+:command:`bdist_wheel` will detect that the code is not pure Python, and build
+a wheel that's named such that it's only usable on the platform that it was
+built on. For details on the naming of wheel files, see :pep:`425`.
 
 .. note::
 
diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
@@ -46,8 +46,9 @@ Examples::
     Requires-Python: ">=3"
     Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
 
-The way to set those values is within the call to `setup` within your setup.py script. This will insert the Requires-Python
-metadata values based on the argument you provide in `python_requires`.
+The way to set those values is within the call to ``setup`` within your
+:file:`setup.py` script. This will insert the ``Requires-Python``
+metadata values based on the argument you provide in ``python_requires``.
 
 .. code-block:: python
 
diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
@@ -23,7 +23,7 @@ Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
 operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
 Windows, NumPy binaries are linked against the `ATLAS
-<http://www.netlib.org/atlas/>` BLAS/LAPACK library, restricted to SSE2
+<http://www.netlib.org/atlas/>`__ BLAS/LAPACK library, restricted to SSE2
 instructions, so they may not provide optimal linear algebra performance.
 
 There are a number of alternative options for obtaining scientific Python
@@ -76,8 +76,8 @@ environments. Allowing access to distributions installed into the system Python
 when using virtual environments is a common approach to working around this
 limitation.
 
-The `wheel` project also provides a `wheel convert` subcommand that can
-convert a Windows `bdist_wininst` installer to a wheel.
+The :term:`wheel` project also provides a :command:`wheel convert` subcommand that can
+convert a Windows :command:`bdist_wininst` installer to a wheel.
 
 .. preserve old links to this heading
 .. _mac-os-x-installers-and-package-managers:
@@ -142,6 +142,6 @@ packages, it is not limited to just Python packages. It has full support for
 native virtual environments. Conda makes environments first-class citizens,
 making it easy to create independent environments even for C libraries. It is
 written in Python, but is Python-agnostic. Conda manages Python itself as a
-package, so that `conda update python` is possible, in contrast to pip, which
-only manages Python packages. Conda is available in Anaconda and Miniconda (an
-easy-to-install download with just Python and conda).
+package, so that :command:`conda update python` is possible, in contrast to
+pip, which only manages Python packages. Conda is available in Anaconda and
+Miniconda (an easy-to-install download with just Python and conda).
diff --git a/source/guides/using-testpypi.rst b/source/guides/using-testpypi.rst
@@ -4,7 +4,7 @@
 Using TestPyPI
 ==============
 
-`TestPyPI` is a separate instance of the :term:`Python Package Index (PyPI)`
+``TestPyPI`` is a separate instance of the :term:`Python Package Index (PyPI)`
 that allows you to try out the distribution tools and process without worrying
 about affecting the real index. TestPyPI is hosted at
 `test.pypi.org <https://test.pypi.org>`_
diff --git a/source/news.rst b/source/news.rst
@@ -164,7 +164,7 @@ September 2017
 
 - Encouraged using ``readme_renderer`` to validate :file:`README.rst`.
   (:pr:`379`)
-- Recommended using the `--user-base` option. (:pr:`374`)
+- Recommended using the ``--user-base`` option. (:pr:`374`)
 
 August 2017
 -----------
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
@@ -562,7 +562,7 @@ Example::
     Requires-Dist: beaglevote[pdf]
     Requires-Dist: libexample[test, doc]
 
-Two feature names `test` and `doc` are reserved to mark dependencies that
+Two feature names ``test`` and ``doc`` are reserved to mark dependencies that
 are needed for running automated tests and generating documentation,
 respectively.
 
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
@@ -212,14 +212,14 @@ Using :ref:`virtualenv`:
 
 For more information, see the `venv`_ docs or the `virtualenv <http://virtualenv.pypa.io>`_ docs.
 
-The use of `source` under Unix shells ensures
+The use of :command:`source` under Unix shells ensures
 that the virtual environment's variables are set within the current
 shell, and not in a subprocess (which then disappears, having no
 useful effect).
 
 In both of the above cases, Windows users should _not_ use the
-`source` command, but should rather run the `activate` script directly
-from the command shell like so:
+:command:`source` command, but should rather run the :command:`activate`
+script directly from the command shell like so:
 
 ::
 
@@ -305,7 +305,7 @@ in the future.
 Upgrading packages
 ==================
 
-Upgrade an already installed `SomeProject` to the latest from PyPI.
+Upgrade an already installed ``SomeProject`` to the latest from PyPI.
 
 ::
 
@@ -484,8 +484,8 @@ Install `setuptools extras`_.
 ----
 
 .. [1] "Secure" in this context means using a modern browser or a
-       tool like `curl` that verifies SSL certificates when downloading from
-       https URLs.
+       tool like :command:`curl` that verifies SSL certificates when
+       downloading from https URLs.
 
 .. [2] Depending on your platform, this may require root or Administrator
        access. :ref:`pip` is currently considering changing this by `making user
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
@@ -115,7 +115,7 @@ minimal set:
   Package>` that should be included in the :term:`distribution package`.
   Instead of listing each package manually, we can use :func:`find_packages`
   to automatically discover all packages and subpackages. In this case, the
-  list of packages will be `example_pkg` as that's the only package present.
+  list of packages will be ``example_pkg`` as that's the only package present.
 - ``classifiers`` gives the index and :ref:`pip` some additional metadata
   about your package. In this case, the package is only compatible with Python
   3, is licensed under the MIT license, and is OS-independent. You should
@@ -229,7 +229,7 @@ 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`. Test
+The first thing you'll need to do is register an account on ``Test PyPI``. Test
 PyPI 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

Original file line number	Diff line number	Diff line change
`@@ -99,8 +99,8 @@`
`99`	`99`
`100`	`100`	# The reST default role (used for this markup: `text`) to use for all
`101`	`101`	`# documents.`
`102`		`-#`
`103`		`-# default_role = None`
	`102`	`+# Ref: python-attrs/attrs#571`
	`103`	`+default_role = 'any' # makes single backticks autofind targets`
`104`	`104`
`105`	`105`	`# If true, '()' will be appended to :func: etc. cross-reference text.`
`106`	`106`	`#`