This proposal seems to have run out of steam.
Python lends itself to inline documentation. With its built-indocstring syntax, a limited form ofLiterate Programming is easy todo in Python. However, there are no satisfactory standard tools forextracting and processing Python docstrings. The lack of a standardtoolset is a significant gap in Python’s infrastructure; this PEP aimsto fill the gap.
The issues surrounding docstring processing have been contentious anddifficult to resolve. This PEP proposes a generic DocstringProcessing System (DPS) framework, which separates out the components(program and conceptual), enabling the resolution of individual issueseither through consensus (one solution) or through divergence (many).It promotes standard interfaces which will allow a variety of plug-incomponents (input context readers, markup parsers, and output formatwriters) to be used.
The concepts of a DPS framework are presented independently ofimplementation details.
There are many aspects to docstring processing. The “Docstring PEPs”have broken up the issues in order to deal with each of them inisolation, or as close as possible. The individual aspects andassociated PEPs are as follows:
By separating out the issues, we can form consensus more easily(smaller fights ;-), and accept divergence more readily.
There are standard inline documentation systems for some otherlanguages. For example, Perl hasPOD (“Plain Old Documentation”) andJava hasJavadoc, but neither of these mesh with the Pythonic way.POD syntax is very explicit, but takes after Perl in terms ofreadability. Javadoc is HTML-centric; except for “@field” tags,raw HTML is used for markup. There are also general tools such asAutoduck andWeb (Tangle & Weave), useful for multiple languages.
There have been many attempts to write auto-documentation systemsfor Python (not an exhaustive list):
These systems, each with different goals, have had varying degrees ofsuccess. A problem with many of the above systems was over-ambitioncombined with inflexibility. They provided a self-contained set ofcomponents: a docstring extraction system, a markup parser, aninternal processing system and one or more output format writers witha fixed style. Inevitably, one or more aspects of each system hadserious shortcomings, and they were not easily extended or modified,preventing them from being adopted as standard tools.
It has become clear (to this author, at least) that the “all ornothing” approach cannot succeed, since no monolithic self-containedsystem could possibly be agreed upon by all interested parties. Amodular component approach designed for extension, where componentsmay be multiply implemented, may be the only chance for success.Standard inter-component APIs will make the DPS componentscomprehensible without requiring detailed knowledge of the whole,lowering the barrier for contributions, and ultimately resulting in arich and varied system.
Each of the components of a docstring processing system should bedeveloped independently. A “best of breed” system should be chosen,either merged from existing systems, and/or developed anew. Thissystem should be included in Python’s standard library.
PyDoc became part of the Python standard library as of release 2.1.It extracts and displays docstrings from within the Python interactiveinterpreter, from the shell command line, and from a GUI window into aweb browser (HTML). Although a very useful tool, PyDoc has severaldeficiencies, including:
<p><small><tt> tags to avoid unwanted linewrapping. Unfortunately, the result is not attractive.The functionality proposed in this PEP could be added to or used byPyDoc when serving HTML pages. The proposed docstring processingsystem’s functionality is much more than PyDoc needs in its currentform. Either an independent tool will be developed (which PyDoc mayor may not use), or PyDoc could be expanded to encompass thisfunctionality andbecome the docstring processing system (or onesuch system). That decision is beyond the scope of this PEP.
Similarly for other existing docstring processing systems, theirauthors may or may not choose compatibility with this framework.However, if this framework is accepted and adopted as the Pythonstandard, compatibility will become an important consideration inthese systems’ future.
The docstring processing system framework is broken up as follows:
PEP 257 documents some of these issues.
These issues are applicable to any docstring processing systemimplementation.PEP 258 documents these issues.
Components 1, 2/3/5, and 4 are the subject of individual companionPEPs. If there is another implementation of the framework orsyntax/parser, additional PEPs may be required. Multipleimplementations of each of components 6 and 7 will be required; thePEP mechanism may be overkill for these components.
A SourceForge project has been set up for this work athttp://docutils.sourceforge.net/.
This document has been placed in the public domain.
This document borrows ideas from the archives of thePythonDoc-SIG. Thanks to all members past & present.
Source:https://github.com/python/peps/blob/main/peps/pep-0256.rst
Last modified:2025-02-01 08:59:27 GMT