[Doc-SIG] Python docs in reST

[Ian Bicking]

Fred L. Drake, Jr. wrote:
>  > While the goal of reST is to avoid explicit markup, IMO it's fine to use
>  > explicit markup where considered necessary and it doesn't make reST less
>  > useful.
> 
> Yep.  I just don't see a way to avoid lots of markup.  There are probably some 
> ways to make the default interpreted text role context-sensitive to avoid 
> having to be really heavy with markup in places where we can determine what's 
> the most reasonable role.  (`var` in a function description with an argument 
> named "var" should be able to determine that `var` refers to the parameter.)

I've always been fuzzy on what `name` really meant in ReST, when it 
doesn't have any other markup.  But it seems vague enough to potentially 
be useful.  Imagine that you specifically name objects that are 
documented, like:

.. class:: ZipFile(file, mode='r', compression=ZIP_STORED)

.. function:: is_zipfile(filename)

Then when you refer to `is_zipfile`, it would know that this referred to 
a function, because of the directive declared elsewhere.  Potentially 
you could have lookup rules that would first search the "local 
namespace" (the module's document), then look for another module (e.g., 
`zlib.compress`).  I'm not sure if it would be reasonable to change the 
documentation to make everything unambiguous, for instance changing this 
zipfile.ZipInfo doc:

   Class used to represent information about a member of an archive. 
Instances of this class are returned by the getinfo() and infolist() 
methods of ZipFile objects.

To:

   Class used to represent information about a member of an archive. 
Instances of this class are returned by the `ZipFile.getinfo()` and 
`ZipFile.infolist()` instance methods.

Ugh.  And I don't know if there's a good way of making indirect links, like:

   ... returned by the `getinfo() <object:ZipFile.getinfo>`_ ...

But, hm... maybe that's not so bad.  You wouldn't know what kind of 
thing you were referencing until you built all the docs (first pass) and 
resolved the links, but I don't know if that's actually a problem.  It's 
just dynamically typed documentation ;)

It *does* seem like "semantic markup" of references is just another way 
of saying "static typing" -- you are giving types to names, when only 
objects should have types.

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org