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
------
If your PEP contains a diagram, you may include it in the processed
output using the "image" directive::
If your PEP contains a diagram or other graphic, you may include it in the
processed output using the ``image`` directive:
.. code-block:: rst
.. image:: diagram.png
Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
.tiff, etc.
Any browser-friendly graphics format is possible; PNG should be
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
text form, you should consider including a description or ASCII art
alternative, using a comment (below).
For accessibility and readers of the source text, you should include
a description of the image and any key information contained within
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
--------
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
the ".." on a line by itself to ensure that the comment is not
misinterpreted as another explicit markup construct. Comments are not
visible in the processed document. For the benefit of those reading
your PEP in source form, please consider including a descriptions of
or ASCII art alternatives to any images you include. For example::
visible in the processed document. For example:
.. image:: dataflow.png
.. code-block:: rst
..
Data flows from the input module, through the "black box"
module, and finally into (and through) the output module.
This section should be updated in the final PEP.
Ensure the date is accurate.
The Emacs stanza at the bottom of this document is inside a comment.