[Python-Dev] Pydoc Improvements (original) (raw)

Fredrik Lundh fredrik at pythonware.com
Fri Jan 5 14:29:11 CET 2007

Talin wrote:

Rather than fixing on a standard markup, I would like to see support for a markup module variable which specifies the specific markup language that is used in that module. Doc processors could inspect that variable and then load the appropriate markup translator.

Ideally, a module should be able to specify what documentation provider to use. Not everyone wants to stuff everything into docstrings, and, especially if you're building larger components, automatic introspection simply doesn't work very well.

fwiw, I have hacks for PythonDoc that monkey-patches "inspect" to provide "virtual docstrings", but it would be nice to have an official API for this. It doesn't have to be much more complicated than:

def __inspect__(path, format_hint=None):
    ...
    return format, data, subpaths

where path is a dotted path to the target object, and format_hint is a preferred format.

Why? Because its hard to get everyone to agree on which markup language is best for documentation. I personally think that reStructuredText is not a good choice, because I want to add markup that adds semantic information, whereas reStructuredText deals solely with presentation and visual appearance.

And does a rather bad job at that too (the "squint if you don't want to see the markup" approach is fundamentally flawed), but that's another story for another forum.

More information about the Python-Dev mailing list