-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
PEP 676: 'dark mode', documentation, spec update, implementation upda…
…te (#2239) Co-authored-by: C.A.M. Gerlach <cam.gerlach@gerlach.cam>
- Loading branch information
1 parent
e4a6c82
commit 50e5de2
Showing
23 changed files
with
573 additions
and
118 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
.. | ||
Author: Adam Turner | ||
|
||
Building PEPs Locally | ||
===================== | ||
|
||
Whilst editing a PEP, it is useful to review the rendered output locally. | ||
This can also be used to check that the PEP is valid reStructuredText before | ||
submission to the PEP editors. | ||
|
||
The rest of this document assumes you are working from a local clone of the | ||
`PEPs repository <https://github.com/python/peps>`__, with Python 3.9 or later | ||
installed. | ||
|
||
|
||
Render PEPs locally | ||
------------------- | ||
|
||
1. Create a virtual environment and install requirements. | ||
|
||
The rest of these instructions assume an active virtual environment named | ||
``venv``. | ||
The Python Packaging User Guide contains | ||
`instructions on creating a virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`__ | ||
for reference. | ||
|
||
.. code-block:: console | ||
(venv) $ python -m pip install --upgrade pip | ||
(venv) $ python -m pip install -r requirements.txt | ||
2. **(Optional)** Delete prior build files. | ||
Generally only needed when making changes to the rendering system itself. | ||
|
||
.. code-block:: console | ||
$ rm -rf build | ||
3. Run the build script: | ||
|
||
.. code-block:: console | ||
(venv) $ make sphinx | ||
If you don't have access to ``make``, run: | ||
|
||
.. code-block:: ps1con | ||
(venv) PS> python build.py | ||
.. note:: | ||
|
||
There may be a series of warnings about unreferenced citations or labels. | ||
Whilst these are valid warnings, they do not impact the build process. | ||
|
||
4. Navigate to the ``build`` directory of your PEPs repo to find the HTML pages. | ||
PEP 0 provides a formatted index, and may be a useful reference. | ||
|
||
|
||
``build.py`` tools | ||
------------------ | ||
|
||
Several additional tools can be run through ``build.py``, or the Makefile. | ||
|
||
|
||
Check links | ||
''''''''''' | ||
|
||
Check the validity of links within PEP sources (runs the `Sphinx linkchecker | ||
<https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder>`__). | ||
|
||
.. code-block:: console | ||
(venv) $ python build.py --check-links | ||
(venv) $ make check-links | ||
Stricter rendering | ||
'''''''''''''''''' | ||
|
||
Run in `nit-picky <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky>`__ | ||
mode. | ||
This generates warnings for all missing references. | ||
|
||
.. code-block:: console | ||
(venv) $ python build.py --nitpicky | ||
Fail the build on any warning. | ||
As of January 2022, there are around 250 warnings when building the PEPs. | ||
|
||
.. code-block:: console | ||
(venv) $ python build.py --fail-on-warning | ||
(venv) $ make fail-warning | ||
``build.py`` usage | ||
------------------ | ||
|
||
For details on the command-line options to the ``build.py`` script, run: | ||
|
||
.. code-block:: console | ||
(venv) $ python build.py --help |
Oops, something went wrong.