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

PEP 12: Update outdated image and comment formatting guidance (#2365)

This commit is contained in:
CAM Gerlach 2022-02-27 14:35:29 -06:00 committed by GitHub
parent d71dae510a
commit d54a624360
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
pep-0012.rst
View File

@ -568,35 +568,43 @@ the numbers will always match.
Images Images
------ ------
If your PEP contains a diagram, you may include it in the processed If your PEP contains a diagram or other graphic, you may include it in the
output using the "image" directive:: processed output using the ``image`` directive:
.. code-block:: rst
.. image:: diagram.png .. image:: diagram.png
Any browser-friendly graphics format is possible: .png, .jpeg, .gif, Any browser-friendly graphics format is possible; PNG should be
.tiff, etc. preferred for graphics, JPEG for photos and GIF for animations.
Currently, SVG must be avoided due to compatibility issues with the
PEP build system.
Since this image will not be visible to readers of the PEP in source For accessibility and readers of the source text, you should include
text form, you should consider including a description or ASCII art a description of the image and any key information contained within
alternative, using a comment (below). using the ``:alt:`` option to the ``image`` directive:
.. code-block:: rst
.. image:: dataflow.png
:alt: Data flows from the input module, through the "black box"
module, and finally into (and through) the output module.
Comments Comments
-------- --------
A comment block is an indented block of arbitrary text immediately A comment is an indented block of arbitrary text immediately
following an explicit markup start: two periods and whitespace. Leave following an explicit markup start: two periods and whitespace. Leave
the ".." on a line by itself to ensure that the comment is not the ".." on a line by itself to ensure that the comment is not
misinterpreted as another explicit markup construct. Comments are not misinterpreted as another explicit markup construct. Comments are not
visible in the processed document. For the benefit of those reading visible in the processed document. For example:
your PEP in source form, please consider including a descriptions of
or ASCII art alternatives to any images you include. For example::
.. image:: dataflow.png .. code-block:: rst
.. ..
Data flows from the input module, through the "black box" This section should be updated in the final PEP.
module, and finally into (and through) the output module. Ensure the date is accurate.
The Emacs stanza at the bottom of this document is inside a comment. The Emacs stanza at the bottom of this document is inside a comment.