Docutils Project Policies
- Contact:
- docutils-develop@lists.sourceforge.net
- Date:
- 2026-05-08
- Revision:
- 10332
- Copyright:
- This document has been placed in the public domain.
The Docutils project group is a meritocracy based on code contribution and lots of discussion [1]. A few quotes sum up the policies of the Docutils project. The IETF's classic credo (by MIT professor Dave Clark) is an ideal we can aspire to:
We reject: kings, presidents, and voting. We believe in: rough consensus and running code.
As architect, chief cook and bottle-washer, David Goodger currently functions as BDFN (Benevolent Dictator For Now). (But he would happily abdicate the throne given a suitable candidate. Any takers?)
Eric S. Raymond, anthropologist of the hacker subculture, writes in his essay The Magic Cauldron:
The number of contributors [to] projects is strongly and inversely correlated with the number of hoops each project makes a user go through to contribute.
We will endeavour to keep the barrier to entry as low as possible. The policies below should not be thought of as barriers, but merely as a codification of experience to date. These are "best practices"; guidelines, not absolutes. Exceptions are expected, tolerated, and used as a source of improvement. Feedback and criticism is welcome.
As for control issues, Emmett Plant (CEO of the Xiph.org Foundation, originators of Ogg Vorbis) put it well when he said:
Open source dictates that you lose a certain amount of control over your codebase, and that's okay with us.
Python Coding Conventions
Contributed code will not be refused merely because it does not strictly adhere to these conditions; as long as it's internally consistent, clean, and correct, it probably will be accepted. But don't be surprised if the "offending" code gets fiddled over time to conform to these conventions.
The Docutils project shall follow the generic coding conventions as specified in the Style Guide for Python Code (PEP 8) and Docstring Conventions (PEP 257), summarized, clarified, and extended as follows:
4 spaces per indentation level. No hard tabs.
Use UTF-8 encoding (no encoding declaration). Identifiers must use ASCII only.
No one-liner compound statements (i.e., no if x: return: use two lines & indentation), except for degenerate class or method definitions (i.e., class X: pass is OK.).
Lines should be no more than 78 characters long.
Use "StudlyCaps" for class names (except for element classes in docutils.nodes).
Use "lowercase" or "lowercase_with_underscores" for function, method, and variable names. For short names, maximum two words, joined lowercase may be used (e.g. "tagname"). For long names with three or more words, or where it's hard to parse the split between two words, use lowercase_with_underscores (e.g., "note_explicit_target", "explicit_target"). If in doubt, use underscores.
Avoid lambda expressions, which are inherently difficult to understand. Named functions are preferable and superior: they're faster (no run-time compilation), and well-chosen names serve to document and aid understanding.
Avoid functional constructs (filter, map, etc.). Use list comprehensions instead.
Avoid from __future__ import constructs. They are inappropriate for production code.
Use 'single quotes' for string literals, and """triple double quotes""" for docstrings.
Documentation Conventions
Docutils documentation is written using reStructuredText, of course.
The encoding of the documentation files is UTF-8.
Use the following section title adornment styles: