Document custom CVE, CWE and PyPI roles (#1307)

Author: hugovk

conf.py

@@ -178,6 +178,7 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
     "github": ("https://github.com/%s/", "%s"),
+    "pypi": ("https://pypi.org/project/%s/", "%s"),
 }
 
 # sphinxext-opengraph config

core-developers/committing.rst

@@ -125,8 +125,7 @@ How to add a NEWS entry
 
 ``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The
 ``NEWS`` entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`_,
-or the `blurb <https://pypi.org/project/blurb/>`_ tool and its ``blurb add``
-command.
+or the :pypi:`blurb` tool and its ``blurb add`` command.
 
 If you are unable to use the tool, then you can create the ``NEWS`` entry file
 manually. The ``Misc/NEWS.d`` directory contains a sub-directory named

developer-workflow/communication-channels.rst

@@ -249,11 +249,11 @@ order to make open source pleasant for everyone involved.
 Additional repositories
 =======================
 
-`Python Core Workflow`_ hosts the codebase for tools such as `blurb`_.
+`Python Core Workflow`_ hosts the codebase for tools such as :pypi:`blurb`.
 
 Other core workflow tools are:
 
-* `cherry_picker`_ (`PyPI`_)
+* `cherry_picker`_ (:pypi:`PyPI <cherry_picker>`)
 * `bedevere`_
 * `blurb_it`_
 * `miss-islington`_
@@ -264,9 +264,7 @@ Python `Performance Benchmark`_ project is intended to be an authoritative
 source of benchmarks for all Python implementations.
 
 .. _Python Core Workflow: https://github.com/python/core-workflow
-.. _blurb: https://pypi.org/project/blurb
 .. _cherry_picker: https://github.com/python/cherry-picker
-.. _PyPI: https://pypi.org/project/cherry_picker/
 .. _bedevere: https://github.com/python/bedevere
 .. _blurb_it: https://github.com/python/blurb_it
 .. _miss-islington: https://github.com/python/miss-islington

documentation/markup.rst

@@ -732,9 +732,12 @@ where simpler markup should be used:
 
 In addition, the CPython documentation defines a few custom roles:
 
-* ``:gh:`ID```: creates a link to a GitHub issue.
-* ``:issue:`ID```: creates a link to a bugs.python.com issue.
-* ``:source:`PATH```: creates a link to a source file on GitHub.
+* ``:cve:`YYYY-NNNNN```: link to a Common Vulnerabilities and Exposures entry.
+* ``:cwe:`NNN```: link to a Common Weakness Enumeration entry.
+* ``:gh:`ID```: link to a GitHub issue.
+* ``:issue:`ID```: link to a bugs.python.com issue.
+* ``:pypi:`NAME```: link to a project on PyPI.
+* ``:source:`PATH```: link to a source file on GitHub.
 
 There are some additional facilities that make cross-referencing roles more
 versatile:

documentation/translating.rst

@@ -209,23 +209,20 @@ Which version of the Python documentation should be translated?
 ---------------------------------------------------------------
 
 Consensus is to work on current stable. You can then propagate your
-translation from one branch to another using `pomerge
-<https://pypi.org/project/pomerge/>`__.
+translation from one branch to another using :pypi:`pomerge`.
 
 
 Are there some tools to help in managing the repo?
 --------------------------------------------------
 
 Here's what we're using:
 
-- `pomerge <https://pypi.org/project/pomerge/>`__ to propagate translations
-  from one file to others.
-- `pospell <https://pypi.org/project/pospell/>`__ to check for typos in ``.po`` files.
-- `powrap <https://pypi.org/project/powrap/>`__ to rewrap the ``.po`` files
+- :pypi:`pomerge` to propagate translations from one file to others.
+- :pypi:`pospell` to check for typos in ``.po`` files.
+- :pypi:`powrap` to rewrap the ``.po`` files
   before committing. This helps keep Git diffs short.
-- `potodo <https://pypi.org/project/potodo/>`__ to list what needs to be translated.
-- `sphinx-lint <https://pypi.org/project/sphinx-lint/>`__ to validate reST syntax in
-  translation files.
+- :pypi:`potodo` to list what needs to be translated.
+- :pypi:`sphinx-lint` to validate reST syntax in translation files.
 
 
 How is a coordinator elected?

getting-started/pull-request-lifecycle.rst

@@ -266,7 +266,7 @@ The automated patch checklist runs through:
 * Has the test suite been updated?
 * Has an entry under ``Misc/NEWS.d/next`` been added?
   (using `blurb-it <https://blurb-it.herokuapp.com/>`_,
-  or the `blurb <https://pypi.org/project/blurb/>`_ tool)
+  or the :pypi:`blurb` tool)
 * Has ``Misc/ACKS`` been updated?
 * Has ``configure`` been regenerated, if necessary?
 * Has ``pyconfig.h.in`` been regenerated, if necessary?

index.rst

@@ -124,7 +124,7 @@ instructions please see the :ref:`setup guide <setup>`.
 
 8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The
    news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`_,
-   or the `blurb <https://pypi.org/project/blurb/>`_ tool and its ``blurb add``
+   or the :pypi:`blurb` tool and its ``blurb add``
    command. Please read more about ``blurb`` in its
    `repository <https://github.com/python/blurb>`_.