Documentation

Documentation

Getting started

Introduction

Building the documentation

Initial requirements

Create a virtual environment

Build using make / make.bat

Build using Sphinx directly

Helping with documentation

Python documentation

Helping with documentation issues

Translating

Proofreading

Style guide

Footnotes

Capitalization

Use simple language

Charged terminology to avoid

Specific words

Type names

Diátaxis

Links

Affirmative tone

Author attribution

Pronunciation of dunder names

Economy of expression

Security considerations (and other concerns)

Code examples

Code equivalents

Audience

Function signatures

reStructuredText markup

Quick reference

reStructuredText primer

Use of whitespace

Paragraphs

Inline markup

Lists and quotes

Source code

Hyperlinks

External links

Internal links

Sections

Explicit markup

Directives

Footnotes

Comments

Source encoding

Gotchas

Typographic conventions

Big O notation

Additional markup constructs

Module-specific markup

Information units

Showing code examples

Roles

Cross-linking markup

Paragraph-level markup

Table-of-contents markup

Index-generating markup

Grammar production displays

Substitutions

Translations

Translating

Overview

Motivation

How to get help

Style guide

Translate the meaning

Gender neutrality

Roles and links

Translation quality

Terminology

Dialects

Code examples

Transifex

Resources

Translation FAQ

How do I build a docs translation?

Which version of the Python documentation should I work on?

How do I translate the Python Docs Sphinx Theme?

The coordination team for my language is inactive, what do I do?

How do I merge translations back in after docs are moved?

Coordinating

Communication/help channels

Starting a new translation

Announcement

Coordination team

Translation team

Repository

Cookiecutter/bootstrapper

Translation platform

Glossary

Moving the repo to the python org

Adding to the language switcher

PEP 545 summary

Translating Sphinx

Coordination FAQ

Are there tools to help in managing the repo?

How should I test my translation?

How is a coordination team chosen?

I have a translation, but it’s not in Git. What should I do?

My Git hierarchy does not match yours. Can I keep it?

What hierarchy should I use in my GitHub repository?

Which version of the Python documentation should be translated?

The entry for my translation is missing or not up to date

How are translations built?

Is there a Weblate instance we can translate on?

Helping with the Developer’s Guide

Developer’s Guide workflow