[Doc-SIG] Python docs in reST
Ian Bicking
ianb at colorstudy.com
Fri May 27 21:56:45 CEST 2005
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
More information about the Doc-SIG
mailing list