PEP 12 – Sample reStructuredText PEP Template | peps.python.org
PEP 12 – Sample reStructuredText PEP Template PEP 12 – Sample reStructuredText PEP Template Author : David Goodger <goodger at python.org>, Barry Warsaw <barry at python.org>, Brett Cannon <brett at python.org> Status : Active Type : Process Created : 05-Aug-2002 Post-History : 30-Aug-2002 22-Feb-2026 Table of Contents Abstract Specification Rationale How to Use This Template ReStructuredText PEP Formatting Requirements General Section Headings Paragraphs Inline Markup Block Quotes Literal Blocks Lists Tables Hyperlinks Internal and PEP/RFC Links Footnotes Images Comments Escaping Mechanism Intersphinx Canonical Documentation Habits to Avoid Suggested Sections Resources Change History Copyright Note For those who have written a PEP before, there is a template (which is included as a file in the PEPs repository ).
Abstract This PEP provides a boilerplate or sample template for creating your own reStructuredText PEPs. In conjunction with the content guidelines in PEP 1 , this should make it easy for you to conform your own PEPs to the format outlined below. Note: if you are reading this PEP via the web, you should first grab the text (reStructuredText) source of this PEP in order to complete the steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE!
The source for this (or any) PEP can be found in the PEPs repository , as well as via a link at the bottom of each PEP. Specification If you intend to submit a PEP, you MUST use this template, in conjunction with the format guidelines below, to ensure that your PEP submission won’t get automatically rejected because of form. Rationale ReStructuredText provides PEP authors with useful functionality and expressivity, while maintaining easy readability in the source text.
The processed HTML form makes the functionality accessible to readers: live hyperlinks, styled text, tables, images, and automatic tables of contents, among other advantages. How to Use This Template To use this template you must first decide whether your PEP is going to be an Informational or Standards Track PEP. Most PEPs are Standards Track because they propose a new feature for the Python language or standard library.
When in doubt, read PEP 1 for details, or open a tracker issue on the PEPs repo to ask for assistance. Once you’ve decided which type of PEP yours is going to be, follow the directions below. Make a copy of this file (the .rst file, not the HTML!) and perform the following edits. Name the new file pep- NNNN .rst , using the next available number (not used by a published or in-PR PEP). Replace the “PEP: 12” header with “PEP: NNNN”, matching the file name.
Note that the file name should be padded with zeros (eg pep-0012.rst ), but the header should not ( PEP: 12 ). Change the Title header to the title of your PEP. Change the Author header to include your name, and optionally your email address. Be sure to follow the format carefully: your name must appear first, and it must not be contained in parentheses. Your email address may appear second (or it can be omitted) and if it appears, it must appear in angle brackets.
It is okay to obfuscate your email address. If none of the authors are Python core developers, include a Sponsor header with the name of the core developer sponsoring your PEP. Add the direct URL of the PEP’s canonical discussion thread (on e.g. Python-Dev, Discourse, etc) under the Discussions-To header. If the thread will be created after the PEP is submitted as an official draft, it is okay to just put “Pending” initially, but remember to update the PEP with the URL as soon as the PEP is successfully merged to the PEPs repository and you create the corresponding discussion thread.
See PEP 1 for more details. Change the Status header to “Draft”. For Standards Track PEPs, change the Type header to “Standards Track”. For Informational PEPs, change the Type header to “Informational”. For Standards Track PEPs, if your feature depends on the acceptance of some other currently in-development PEP, add a Requires header right after the Type header. The value should be the PEP number of the PEP yours depends on.
Don’t add this header if your dependent feature is described in a Final PEP. Change the Created header to today’s date. Be sure to follow the format carefully: it must be in DD-MMM-YYYY format, where the MMM is the three-letter English month abbreviation, i.e. one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. For Standards Track PEPs, after the Created header, add a Python-Version header and set the value to the next planned version of Python, i.e. the one your new feature will hopefully make its first appearance in.
Do not use an alpha or beta release designation here. Thus, if the last version of Python was 2.2 alpha 1 and you’re hoping to get your new feature into Python 2.2, set the header to: Python-Version: 2.2 Add a Topic header if the PEP belongs under one shown at the Topic Index . Most PEPs don’t. Post-History can be ‘Pending’ for now; you’ll add dates and corresponding links to this header each time you post your PEP to the designated discussion forum (and update the Discussions-To header with said link, as above).
For each thread, use the date (in the DD-MMM-YYYY format) as the linked text, and insert the URLs inline as anonymous reST hyperlinks , with commas in between each posting. If you posted threads for your PEP on August 14, 2001 and September 3, 2001, the Post-History header would look like, e.g.: Post-History: `14-Aug-2001 <https:// www.example.com /thread_1>`__, `03-Sept-2001 <https:// www.example.com /thread_2>`__ You should add the new dates/links here as soon as you post a new discussion thread.
Add a Replaces header if your PEP obsoletes an earlier PEP. The value of this header is the number of the PEP that your new PEP is replacing. Only add this header if the older PEP is in “final” form, i.e. is either Accepted, Final, or Rejected. You aren’t replacing an older open PEP if you’re submitting a competing idea. Now write your Abstract, Rationale, and other content for your PEP, replacing all this gobbledygook with your own text.
Be sure to adhere to the format guidelines below, specifically on the prohibition of tab characters and the indentation requirements. See “Suggested Sections” below for a template of sections to include. Update your Footnotes section, listing any footnotes and non-inline link targets referenced by the text. Run ./build.py to ensure the PEP is rendered without errors, and check that the output in build/pep- NNNN .html looks as you intend.
Create a pull request against the PEPs repository . For reference, here are all of the possible header fields (everything in brackets should either be replaced or have the field removed if it has a leading * marking it as optional and it does not apply to your PEP): PEP: [NNN] Title: [...] Author: [Full Name <email at example.com >] Sponsor: *[Full Name <email at example.com >] PEP-Delegate: Discussions-To: [URL] Status: Draft Type: [Standards Track | Informational | Process] Topic: *[Governance | Packaging | Release | Typing] Requires: *[NNN] Created: [DD-MMM-YYYY] Python-Version: *[M.N] Post-History: [`DD-MMM-YYYY <URL>`__] Replaces: *[NNN] Superseded-By: *[NNN] Resolution: ReStructuredText PEP Formatting Requirements The following is a PEP-specific summary of reStructuredText syntax.
For the sake of simplicity and brevity, much detail is omitted. For more detail, see Resources below. Literal blocks (in which no markup processing is done) are used for examples throughout, to illustrate the plaintext markup. General Lines should usually not extend past column 79, excepting URLs and similar circumstances. Tab characters must never appear in the document at all. Section Headings PEP headings must begin in column zero and the initial letter of each word must be capitalized as in book titles.
Acronyms should be in all capitals. Section titles must be ado
The rest of this page is on the live site.