Style guide
Skip to content Back to top View this page Edit this page Style guide ¶ This page describes the linguistic style guide for our documentation. For markup details in reST files, see reStructuredText markup . Footnotes ¶ Footnotes are generally discouraged, though they may be used when they are the best way to present specific information. When a footnote reference is added at the end of the sentence, it should follow the sentence-ending punctuation.
The reST markup should appear something like this: This sentence has a footnote reference. [#]_ This is the next sentence. Footnotes should be gathered at the end of a file, or if the file is very long, at the end of a section. The docutils will automatically create backlinks to the footnote reference. Footnotes may appear in the middle of sentences where appropriate. Capitalization ¶ In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule.
If you add a section to a chapter where most sections are in title case, you can either convert all titles to sentence case or use the dominant style in the new section title. Sentences that start with a word for which specific rules require starting it with a lowercase letter should be avoided. Note Sections that describe a library module often have titles in the form of “modulename — Short description of the module.” In this case, the description should be capitalized as a stand-alone sentence.
Many special names are used in the Python documentation, including the names of operating systems, programming languages, standards bodies, and the like. Most of these entities are not assigned any special markup, but the preferred spellings are given in Specific words to aid authors in maintaining the consistency of presentation in the Python documentation. Use simple language ¶ Avoid esoteric phrasing where possible.
Our audience is world-wide and may not be native English speakers. Don’t use Latin abbreviations like “e.g.” or “i.e.” where English words will do, such as “for example” or “that is.” In general, the first time an acronym or abbreviation is used on a page, spell it out. Prefer to write out the full term and follow it with the acronym in parentheses. For example, write “Basic Multilingual Plane (BMP)”.
Commonly understood acronyms, such as “HTML” and “UTF-8”, should not be expanded. Charged terminology to avoid ¶ Avoid terminology that may be considered insensitive or exclusionary. Avoid Instead whitelist allowlist blacklist blocklist, denylist master/slave main, parent/child, server/client, primary/secondary Specific words ¶ Some terms and words deserve special mention. These conventions should be used to ensure consistency throughout the documentation: boolean Lowercase in most instances.
Uppercase for Boolean mathematics and Boolean logic . To refer to the Python or C data type, prefer using the exact, abbreviated name with appropriate markup (for example, :type:`bool` ). C API Python’s API used by C programmers to write extension modules. All caps and unhyphenated. CPU Central processing unit. No need to spell out. free-threaded The preferred term for the build mode that makes the global interpreter lock (GIL) optional (per PEP 703 ).
Avoid using “No-GIL” to avoid double negatives (for example, “non-no-GIL”). open source Follow the usual English rules for compound words. When used as an adjective, hyphenate: “open-source software”. When used as a noun, don’t use a hyphen: “open source is a collaboration model.” POSIX The name assigned to a particular group of standards. This is always uppercase. Python The name of our favorite programming language is always capitalized. reST For “reStructuredText,” an easy to read, plain-text markup syntax used to produce Python documentation.
When spelled out, it is always one word and both forms start with a lowercase ‘r’. time zone When referring to a Python term like a module, class, or argument spell it as one word with appropriate markup (for example, :mod:`timezone` ). When talking about the real-world concept spell it as two words with no markup. Unicode The name of a character coding system. This is always written capitalized. Unix The name of the operating system developed at AT&T Bell Labs in the early 1970s.
Type names ¶ When writing the names of types in prose, indicate that the name is a type by writing the name of the type exactly as it appears in source, styled as a class reference or an unlinked class. For example, refer to dict as :class:`dict` or :class:`!dict` . Links should be used according to the guidance on links . Some type names are commonly understood ideas or nouns outside of Python. For example, “tuples” are a general programming concept, as distinct from the tuple type.
When referring to general ideas, do not style the relevant word as a type. Many types have descriptive names which may or may not exactly match their type name. For example, “context variables” describes contextvars.ContextVar , and both “dict” and “dictionary” are used to describe dict . Once it is clear that the text refers to a specific type, use the naming which suits the context: in the case of dict , any of “dict”, “dictionary”, or “ :class:`dict` ” may be best.
Descriptive names should be written as common nouns, meaning they are lowercase when not at the start of a sentence or phrase. Diátaxis ¶ Python’s documentation strives to follow the Diátaxis framework. This means adapting the writing style according to the nature of the documentation that is being written. The framework splits documentation into four distinct types: tutorials, how-to guides, reference, and explanation.
The Python Tutorial should be explicit and avoid making assumptions about the reader’s knowledge. The goal of a tutorial is to get the user writing Python code as quickly as possible with clear logical steps. Explanations and abstract concepts should be avoided. Please consult the Diátaxis guide on Tutorials for more detail. Python how-to guides are designed to guide a user through a problem-field. Both tutorials and how-to guides are instructional rather than explanatory and should provide logical steps on how to complete a task.
However, how-to guides make more assumptions about the user’s knowledge and focus on the user finding the best way to solve their own particular problem. The Python Language Reference should be factual and succinct. The purpose of reference documentation is to describe rather than to explain. Accuracy and consistency are key as this type of documentation should be seen as an authoritative source. Code examples can be a useful way of achieving these objectives.
Python explanations provide a deeper level of understanding and are naturally more discursive. They aim to deepen the reader’s understanding and answer ‘why’ questions. They should provide context, make connections between topics, and discuss alternative opinions. There is no section dedicated to explanations but these can be found throughout Python’s documentation, for example the Unicode HOWTO . Please consult the Diátaxis guide for more detail.
Links ¶ Links are a powerful tool for helping people navigate documentation and find more information, but links can be over-used. Links should be used only if they help the reader. Generally, a link should be provided for the first use of a term in a unit, such as a section or paragraph. This is not a hard and fast rule. Sometimes the second mention is more appropriate for a link. Some units are long enough to have a few repeated links.
Use judgement to decide when a link will help the reader. We use the linklint Sphinx extension to suppress two kinds of excessive links: references in a section to itself and duplicate references in a paragraph. Previously, editors had to carefully use an exclamation
The rest of this page is on the live site.