7. Documenting Python — Python Developer's Guide. The Python language has a substantial body of documentation, much of it contributed by various authors.
The markup used for the Python documentation is reStructuredText, developed by the docutils project, amended by custom directives and using a toolset named Sphinx to post-process the HTML output. This document describes the style guide for our documentation as well as the custom reStructuredText markup introduced by Sphinx to support Python documentation and how it should be used. 7.1. Introduction Python’s documentation has long been considered to be good for a free programming language. The involvement of the community takes many forms, from authoring to bug reports to just plain complaining when the documentation could be more complete or easier to use. This document is aimed at authors and potential authors of documentation for Python. Docstring Conventions. What is a Docstring?
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object. All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings.
A package may be documented in the module docstring of the __init__.py file in the package directory. String literals occurring elsewhere in Python code may also act as documentation. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".String literals occurring immediately after another docstring are called "additional docstrings".
Please see PEP 258, "Docutils Design Specification" , for a detailed description of attribute and additional docstrings. Multi-line Docstrings. Docutils Design Specification. Docutils Project Model Project components and data flow: +---------------------------+ | Docutils: | | docutils.core.Publisher, | | docutils.core.publish_*() | +---------------------------+ / | \ / | \ 1,3,5 / 6 | \ 7 +--------+ +-------------+ +--------+ | READER | ----> | TRANSFORMER | ====> | WRITER | +--------+ +-------------+ +--------+ / \\ | / \\ | 2 / 4 \\ 8 | +-------+ +--------+ +--------+ | INPUT | | PARSER | | OUTPUT | +-------+ +--------+ +--------+ The numbers above each component indicate the path a document's data takes.
Double-width lines between Reader & Parser and between Transformer & Writer indicate that data sent along these paths should be standard (pure & unextended) Docutils doc trees. Single-width lines signify that internal tree extensions or completely unrelated representations are possible, but they must be supported at both ends. Publisher Readers Each reader is a module or package exporting a "Reader" class with a "read" method. Responsibilities: Examples: Docutils Project Documentation Overview. The latest working documents may be accessed individually below, or from the docs directory of the Docutils distribution.
Docutils stakeholders can be categorized in several groups: A ReStructuredText Primer. The text below contains links that look like "(quickref)".
These are relative links that point to the Quick reStructuredText user reference. If these links don't work, please refer to the master quick reference document. Note This document is an informal introduction to reStructuredText. The What Next? From the outset, let me say that "Structured Text" is probably a bit of a misnomer. The most basic pattern recognised is a paragraph (quickref). This is a paragraph.
Results in: This is a paragraph. This paragraph will result in an indented block of text, typically used for quoting other text. This is another one. (quickref) Inside paragraphs and other bodies of text, you may additionally mark text for italics with "*italics*" or bold with "**bold**". If you want something to appear as a fixed-space literal, use "``double back-quotes``". If you find that you want to use one of the "special" characters in text, it will generally be OK -- reStructuredText is pretty smart. Tip what how (quickref)
Epydoc. Comparison of documentation generators. The following tables compare general and technical information for a number of documentation generators.
Please see the individual products' articles for further information. Unless otherwise specified in footnotes, comparisons are based on the stable versions without any add-ons, extensions or external programs. General information[edit] Basic general information about the generators: creator/company, license/price etc. Operating system support[edit] The operating systems the generators can run on. Note (4): GNU D Compiler. Language support[edit] The programming languages the generators recognize. Note (1): .NET is not a programming language, but is listed here for convenience. Note (2): Though not supported as a native input language, Doxygen can be extended through the use of filters.
Note (3): Generators listed here can be extended to support any language that has comments. Input formats[edit] The input formats the generators can read. Output formats[edit] Other features[edit] GhostDoc. Other Documentation Tools. <h3>Other Documentation Tools</h3> <p>When considering the state of documentation tools for Python, one should consider what is being done for other systems.
This should include tools that work with documentation embedded in source code and tools that work with separated documentation. </p> <p>If you can think of additional tools that should be noted, please let me know about them (free or commercial). If you can point to an example of the markup, that would be great; thanks! <h3>Source-embedded Documentation</h3> 25.1. pydoc — Documentation generator and online help system — Python v2.7.2 documentation. Source code: Lib/pydoc.py The pydoc module automatically generates documentation from Python modules.
The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files. For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()). The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. Overview — Sphinx 1.1.3 documentation.