iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sphinx support: Add build process notes to README.rst (#2016) 

Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
This commit is contained in:
Adam Turner 2021-07-01 00:56:07 +01:00 committed by GitHub
parent 2991089ed8
commit 977f1fe68a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 57 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
README.rst
View File

@ -70,3 +70,60 @@ rendering pipeline:
local clone of the PEP repository
* Run ``./manage.py generate_pep_pages`` as described in
https://pythondotorg.readthedocs.io/pep_generation.html
Rendering PEPs with Sphinx
==========================
There is a Sphinx-rendered version of the PEPs at https://python.github.io/peps/
(updated on every push to ``master``)
**Warning:** This version is not, and should not be taken to be, a canonical
source for PEPs whilst it remains in preview (`please report any rendering bugs
<https://github.com/python/peps/issues/new>`_). The canonical source for PEPs remains
https://www.python.org/dev/peps/
Build PEPs with Sphinx locally:
-------------------------------
1. Ensure you have Python >=3.9 and Sphinx installed
2. If you have access to ``make``, follow (i), otherwise (ii)
i. Run ``make sphinx-local``
ii. Run ``python build.py -j 8 --build-files``. Note that the jobs argument
only takes effect on unix (non-mac) systems.
3. Wait for Sphinx to render the PEPs. 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.
Arguments to ``build.py``:
--------------------------
Renderers:
``-f`` or ``--build-files``
Renders PEPs to ``pep-XXXX.html`` files
``-d`` or ``--build-dirs``
Renders PEPs to ``index.html`` files within ``pep-XXXX`` directories
Options:
``-i`` or ``--index-file``
Copies PEP 0 to a base index file
``-j`` or ``--jobs``
How many parallel jobs to run (if supported). Integer, default 1
``-n`` or ``--nitpicky``
Runs Sphinx in `nitpicky` mode
``-w`` or ``--fail-on-warning``
Fails Sphinx on warnings
Tools:
``-l`` or ``--check-links``
Checks validity of links within PEP sources