[Python-Dev] The docs, reloaded

[Georg Brandl]

Talin schrieb:
> Martin Blais wrote:
>> On 5/22/07, Martin Blais <blais at furius.ca> wrote:
>>> ReST works well only when there is little markup.  Writing code
>>> documentation generally requires a lot of markup, you want to make
>>> variables, classes, functions, parameters, constants, etc..  (A better
>>> avenue IMHO would be to augment docutils with some code to
>>> automatically figure out the syntax of functions, parameters, classes,
>>> etc., i.e., less markup, and if we do this in Python we may be able to
>>> use introspection.  This is a challenge, however, I don't know if it
>>> can be done at all.)
>> 
>> Just to follow-up on that idea: I don't think it would be very
>> difficult to write a very small modification to docutils that
>> interprets the default role with more "smarts", for example, you can
>> all guess what the types of these are about:
>> 
>>   `class Foo`  (this is a class Foo)
>>   `bar(a, b, c) -> str`  (this is a function "bar" which returns a string)
>>   `name (attribute)`  (this is an attribute)

What's better here than :class:`Foo` or :attr:`name`?
You wouldn't want to put an " (attribute)" after all references to it
in your text, so this is just an alternative way to spell roles.

>> ...so why couldn't the computer solve that problem for you?  I'm sure
>> we could make it happen.  Essentially, what is missing from ReST is
>> "less markup for documenting programs".  By restricting the
>> problem-set to Python programs, we can go a long way towards making
>> much of this automatic, even without resorting to introspecting the
>> source code that is being documented.
> 
> I was going to suggest something similar.
> 
> Ideally, any markup language ought to have a kind of "Huffman Coding" of 
> complexity - in other words, the markup symbols that are used the most 
> frequently are the ones that should be the shortest and easiest to type.
> 
> Just as in real Huffman Coding, the popularity of a given element is 
> going to depend on context. This would imply that there should be 
> customizations of the markup language for different knowledge domains.
> 
> While there are some benefits to having a 'standard' markup, any truly 
> universal markup is going to be much heavier and more cumbersome than 
> one that is specialized for the task.
> 
> I would advocate a system in which the author inserts minimalistic 
> 'hints' into the text, and the document processor uses those hints along 
> with some automatic reasoning to determine the final markup. As in the 
> above example, the use of backticks can be signal to the document 
> processor that the enclosed text should be examined for identifiers and 
> other Python syntax.

What I could propose is that we could abandon :class:`foo`, :meth:`foo` etc.
and just use `foo`. There shouldn't be too many cases where this gets
ambiguous crossreferencing.

Variables would just use *var*, since they're not marked up speciall anyways.

> I would also suggest that one test for evaluating the quality of markup 
> syntax is whether or not it can be learned by example - can a user 
> follow the pattern of some other part of the docs, without having to 
> learn the syntax in a formal way?

I think he/she can, given a piece of document that contains most of the
needed markup constructs.

You'll pretty soon grok that reST uses indentation (and you'll be pleased
with it if you like Python, which seems a reasonable assumption ;).
You'll also get that :foo:`bar` is the syntax for semantic inline markup.
Code examples are always introduced with a "::" (okay, the exact rules are
a bit nifty, but very convenient if you know them).

What else do you need to know? ".. function::" directives are quite easy
to recognize.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.