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>
_______________________________________________
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
