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>