[Python-Dev] Pydoc Improvements / Rewrite

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.

</F> 





More information about the Python-Dev mailing list