[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