Update, copyedit and format README and Contributing Guide (#2352)

CONTRIBUTING.rst

@@ -1,55 +1,49 @@
 Contributing Guidelines
 =======================
 
-To learn more about the purpose of PEPs and how to go about writing a PEP, please
-start reading at PEP 1 (`pep-0001.txt <./pep-0001.txt>`_ in this repo). Note that
-PEP 0, the index PEP, is now automatically generated, and not committed to the repo.
+To learn more about the purpose of PEPs and how to go about writing one, please
+start reading at `PEP 1 <https://www.python.org/dev/peps/pep-0001/>`_.
+Also, make sure to check the `README <./README.rst>`_ for information
+on how to render the PEPs in this repository.
+Thanks again for your contributions, and we look forward to reviewing them!
+
 
 Before writing a new PEP
 ------------------------
 
-Has this idea been proposed on `python-ideas <https://mail.python.org/mailman/listinfo/python-ideas>`_
-and received general acceptance as being an idea worth pursuing? (if not then
-please start a discussion there before submitting a pull request).
-
-More details about it in `PEP 1 <https://www.python.org/dev/peps/pep-0001/#start-with-an-idea-for-python>`_.
+Prior to submitting a pull request here with your draft PEP, see `PEP 1
+<https://www.python.org/dev/peps/pep-0001/#start-with-an-idea-for-python>`_
+for some important steps to consider, including proposing and discussing it
+first in an appropriate venue, drafting a PEP and gathering feedback, and
+developing at least a prototype reference implementation of your idea.
 
-Do you have an implementation of your idea? (this is important for when you
-propose this PEP to `python-dev <https://mail.python.org/mailman/listinfo/python-dev>`_
-as code maintenance is a critical aspect of all PEP proposals prior to a
-final decision; in special circumstances an implementation can be deferred)
 
+Commit messages and PR titles
+-----------------------------
 
-Commit messages
----------------
-
-When committing to a PEP, please always include the PEP number in the subject
-title. For example, ``PEP NNN: <summary of changes>``.
+When adding or modifying a PEP, please always include the PEP number in the
+commit summary and pull request title.
+For example, ``PEP NNN: <summary of changes>``.
 
 
 Sign the CLA
 ------------
 
 Before you hit "Create pull request", please take a moment to ensure that this
 project can legally accept your contribution by verifying you have signed the
-PSF Contributor Agreement:
-
-    https://www.python.org/psf/contrib/contrib-form/
-
-If you haven't signed the CLA before, please follow the steps outlined in the
-CPython devguide to do so:
-
-    https://devguide.python.org/pullrequest/#licensing
+`PSF Contributor Agreement <https://www.python.org/psf/contrib/contrib-form/>`_.
 
-Thanks again to your contribution and we look forward to looking at it!
+If you haven't signed the CLA before, please follow the
+`steps outlined in the CPython devguide
+<https://devguide.python.org/pullrequest/#licensing>`_ to do so.
 
 
 Code of Conduct
 ---------------
 
 All interactions for this project are covered by the
 `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`_. Everyone is
-expected to be open, considerate, and respectful of others no matter their
+expected to be open, considerate, and respectful of others, no matter their
 position within the project.
 
 
@@ -76,27 +70,27 @@ before running this command.
 
 Otherwise, you can install pre-commit with
 
-.. code-block:: console
+.. code-block:: bash
 
     python -m pip install pre-commit
 
 (or your choice of installer), and then run the hooks on all the files
 in the repo with
 
-.. code-block:: console
+.. code-block:: bash
 
     pre-commit run --all-files
 
 or only on any files that have been modified but not yet committed with
 
-.. code-block:: console
+.. code-block:: bash
 
     pre-commit run
 
 If you would like pre-commit to run automatically against any modified files
 every time you commit, install the hooks with
 
-.. code-block:: console
+.. code-block:: bash
 
     pre-commit install
 
@@ -119,13 +113,13 @@ For finer control or on other systems, after installing pre-commit as in
 the previous section, you can run it against only the files
 you've modified and not yet committed with
 
-.. code-block:: console
+.. code-block:: bash
 
     pre-commit run --hook-stage manual codespell
 
 or against all files with
 
-.. code-block:: console
+.. code-block:: bash
 
     pre-commit run --all-files --hook-stage manual codespell
 

README.rst

@@ -6,9 +6,10 @@ Python Enhancement Proposals
 
 The PEPs in this repo are published automatically on the web at
 https://www.python.org/dev/peps/.  To learn more about the purpose of
-PEPs and how to go about writing a PEP, please start reading at PEP 1
-(``pep-0001.txt`` in this repo).  Note that PEP 0, the index PEP, is
-now automatically generated, and not committed to the repo.
+PEPs and how to go about writing one, please start reading at `PEP 1
+<https://www.python.org/dev/peps/pep-0001/>`_.
+Note that PEP 0, the index PEP, is
+automatically generated and not committed to the repo.
 
 
 Contributing to PEPs
@@ -20,16 +21,18 @@ See the `Contributing Guidelines <./CONTRIBUTING.rst>`_.
 reStructuredText for PEPs
 =========================
 
-Original PEP source should be written in reStructuredText format,
+PEP source text should be written in reStructuredText format,
 which is a constrained version of plaintext, and is described in
-PEP 12.  Older PEPs were often written in a more mildly restricted
-plaintext format, as described in PEP 9.  The ``pep2html.py``
-processing and installation script knows how to produce the HTML
-for either PEP format.
+`PEP 12 <https://www.python.org/dev/peps/pep-0012/>`_.
+The ``pep2html.py`` processing and installation script knows
+how to produce the HTML for the PEP format.
 
-For processing reStructuredText format PEPs, you need the docutils
-package, which is available from `PyPI <https://pypi.org/>`_.
-If you have pip, ``pip install docutils`` should install it.
+To render the PEPs, you'll first need to install the requirements,
+(preferably in a fresh virtual environment):
+
+.. code-block:: bash
+
+    python -m pip install -r requirements.txt
 
 
 Generating the PEP Index
@@ -49,13 +52,13 @@ intend. To check building the HTML output for your PEP (for example, PEP 12)
 using the current default docutils-based system, run the ``pep2html.py`` script
 with your PEP source file as its argument; e.g. for PEP 12,
 
-.. code-block:: console
+.. code-block:: bash
 
     python pep2html.py pep-0012.rst
 
 If you're on a system with ``make``, you can instead execute, e.g.,
 
-.. code-block:: console
+.. code-block:: bash
 
     make pep-0012.rst
 
@@ -78,24 +81,25 @@ either on-demand or automatically as you commit, with our pre-commit suite.
 See the `Contributing Guide <./CONTRIBUTING.rst>`_ for details.
 
 
-Generating HTML for python.org
+Generating HTML for Python.org
 ==============================
 
-python.org includes its own helper modules to render PEPs as HTML, with
+Python.org includes its own helper modules to render PEPs as HTML, with
 suitable links back to the source pages in the version control repository.
 
-These can be found at https://github.com/python/pythondotorg/tree/main/peps
+These can be found `in the python.org repository
+<https://github.com/python/pythondotorg/tree/main/peps>`__.
 
 When making changes to the PEP management process that may impact python.org's
 rendering pipeline:
 
-* Clone the python.org repository from https://github.com/python/pythondotorg/
-* Get set up for local python.org development as per
-  https://pythondotorg.readthedocs.io/install.html#manual-setup
+* Clone the `python.org repository <https://github.com/python/pythondotorg/>`_.
+* Get `set up for local python.org development
+  <https://pythondotorg.readthedocs.io/install.html#manual-setup>`_.
 * Adjust ``PEP_REPO_PATH`` in ``pydotorg/settings/local.py`` to refer to your
-  local clone of the PEP repository
-* Run ``./manage.py generate_pep_pages`` as described in
-  https://pythondotorg.readthedocs.io/pep_generation.html
+  local clone of the PEP repository.
+* Run ``./manage.py generate_pep_pages`` as described the `python.org docs
+  <https://pythondotorg.readthedocs.io/pep_generation.html>`__.
 
 
 Rendering PEPs with Sphinx
@@ -119,19 +123,19 @@ instructions on how to install, build and view the rendered PEPs with Sphinx.
 In summary, after installing the dependencies (preferably in a virtual
 environment) with:
 
-.. code-block:: console
+.. code-block:: bash
 
     python -m pip install -r requirements.txt
 
 You can build the PEPs with sphinx by running, if your system has ``make``:
 
-.. code-block:: console
+.. code-block:: bash
 
     make sphinx
 
 Otherwise, execute the ``build.py`` script directly:
 
-.. code-block:: console
+.. code-block:: bash
 
     python build.py
 
@@ -143,6 +147,6 @@ The output HTML can be found under the ``build`` directory.
 
 For details on the command-line options to the ``build.py`` script, run:
 
-.. code-block:: console
+.. code-block:: bash
 
     python build.py --help