Docutils: Documentation Utilities

Ian Bicking wrote:
> Okay, I'm messing around with the document extractor again, and trying
> to document a specific class.  The class has a lot of methods, and I'd
> like to categorize them.  I've also been using blockquotes to represent
> the nesting of the methods in the class and the class in the module.

Why use blockquotes?

> Now, I'd like **Accessors** to actually be a header, like:
> 
>    Accessors
>    ---------
>
> But I don't believe reST allows a header in a blockquote.  **Accessors**
> isn't too bad, and I can still put in a link target, but the thing I
> *really* want is a table of contents.

So make it a header.  Don't use blockquotes.

> Though, as I realize it, I *really* want a table of contents that
> includes the function definitions, so it'd be like:
> 
> HTTPRequest
>     Accessors
>         transaction
>         setTransaction
>         time
> 
> So that's even further from what reST is doing.  What might I do to
> achieve that kind of formating?  A table of contents like that would be
> quite important.

Stop fighting the markup.  ReStructuredText doesn't use indentation for
large-scale structure, only for local constructs (lists etc.).  If it sounds
like a duck and acts like a duck, it's a duck.  Use section structure, and
the table of contents is easy, cross-references are easy.

If you want the output to have indentation for each section level, you can
do that in the stylesheet.  Don't let style dictate structure.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

On Sat, 2003-01-25 at 10:10, David Goodger wrote:
> Stop fighting the markup.  ReStructuredText doesn't use indentation for
> large-scale structure, only for local constructs (lists etc.).  If it sounds
> like a duck and acts like a duck, it's a duck.  Use section structure, and
> the table of contents is easy, cross-references are easy.
> 
> If you want the output to have indentation for each section level, you can
> do that in the stylesheet.  Don't let style dictate structure.

Okay, so now I'm doing that, without indentation.  Except for
functions/methods, where the actual docstring is indented, as in:

`function_name(params)`:
    The docstring.

Which probably won't cause any problem.  But now I'm trying to get the
functions in the table of contents.  Now, I could make each function a
title, like

function_name(params):
**********************

The docstring

But I don't think I can get that to look like I want, even with fancy
CSS.  Not to mention that I don't know at what level (h1, h2, h3, etc)
the function definition will be -- it's largely orthogonal to other
structure.  Hmm... what I'd really like is a directive, like:

.. header:: function_name

That would create an invisible sort of header, where it shows up in the
TOC and is a link target, but isn't otherwise displayed.  Of course,
"function_name" always the name of the target, I've been using
"ClassName.function_name".  So something like:

.. header:: function_name
   :anchor-name: ClassName.function_name

Anyway, that's my initial thought.  Maybe there's a different way to do
this.

Also, would there be a way to create a smaller TOC for a section?  I'm
thinking about putting several modules in one document, to make
interlinking easier, to make the public interface easier to navigate
(since the interface is made up of the methods from several classes that
inherit from each other).  It would be nice to have a TOC for each
class, for instance.

Thanks,
  Ian

[David Goodger]
>> Stop fighting the markup.  ReStructuredText doesn't use indentation
>> for large-scale structure, only for local constructs (lists etc.).
>> If it sounds like a duck and acts like a duck, it's a duck.  Use
>> section structure, and the table of contents is easy,
>> cross-references are easy.
>> 
>> If you want the output to have indentation for each section level,
>> you can do that in the stylesheet.  Don't let style dictate
>> structure.

[Ian Bicking]
> Okay, so now I'm doing that, without indentation.  Except for
> functions/methods, where the actual docstring is indented, as in:
> 
> `function_name(params)`:
>     The docstring.
> 
> Which probably won't cause any problem.  But now I'm trying to get
> the functions in the table of contents.

That construct is a definition list.  If that's what you want, fine,
but there's no support for adding it to the TOC.

Also, did you intend literals (``) instead of interpreted text (`)?

> Now, I could make each function a title, like
> 
> function_name(params):
> **********************
> 
> The docstring
> 
> But I don't think I can get that to look like I want, even with
> fancy CSS.

What do you want it to look like?

> Not to mention that I don't know at what level (h1, h2, h3, etc)
> the function definition will be -- it's largely orthogonal to other
> structure.  Hmm... what I'd really like is a directive, like:
> 
> .. header:: function_name
> 
> That would create an invisible sort of header, where it shows up in
> the TOC and is a link target, but isn't otherwise displayed.  Of
> course, "function_name" always the name of the target, I've been
> using "ClassName.function_name".  So something like:
> 
> .. header:: function_name
>    :anchor-name: ClassName.function_name
>
> Anyway, that's my initial thought.  Maybe there's a different way to
> do this.

I don't think this is a good approach.  It smells like a kludge: too
single-purpose to be worthwhile, and very magical.  How would this
translate into elements in the doctree?  The doctree must remain
self-consistent and style-free (as much as possible).

Although I still suspect you're letting style dictate structure, I'll
try to help you out.  But we must recognize that there are limits to
reStructuredText, beyond which we have to consider alternatives.
ReStructuredText is aimed at ordinary documents; it's not suitable for
some really creative graphic design exercises, and I don't think it
should be.

It seems that you're looking for finer-grained selectability, to be
able to more precisely target styles.  Currently we have two extremes:
overly broad (a <div> element surrounds every section, but different
"types" of sections are not distinct from each other), and overly
precise (each <div> section element has a unique "id" attribute, which
*could* be used in the stylesheet, but it would be a manual pain).

Perhaps the "topic" directive would suit your purposes.  See
<http://docutils.sf.net/spec/rst/directives.html#topic>, and note that
topics cannot contain subsections or subtopics.  Currently, topics
don't show up in the table of contents, but that could be remedied
with a new option to the "contents" directive.

As for "anchor-name", that can be a simple internal hyperlink target.
Together, it would look something like this::

    .. contents::
       :topics:

    .. _ClassName.function.name:

    .. topic:: 

Docutils uses an optional "class" attribute on all elements, which is
carried all the way through the HTML writer.  The class attribute can
contain multiple values (space-separated).  A new directive could be
added that adds a class value to the enclosing element, and this class
could be selected in the stylesheet.  If the section *containing* the
specialized function sections is given a class, say
"function-container", the stylesheet could contain a style like this::

    div.function-container div { ... your styles here ... }

I'll add these to the to-do list.  Contributions are welcome!

> Also, would there be a way to create a smaller TOC for a section?

Yes, you can use the "contents" directive with the ":local:" option:

    Generate a local table of contents.  Entries will only include
    subsections of the section in which the directive is given.  If no
    explicit title is given, the table of contents will not be titled.

The ":depth:" option may also be useful:

    The number of section levels that are collected in the table of
    contents.  The default is unlimited depth.

See <http://docutils.sf.net/spec/rst/directives.html#table-of-contents>
for details, and <http://docutils.sf.net/spec/doctree.html> for
examples of both options.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

On Wednesday, January 29, 2003, at 02:16 PM, David Goodger wrote:
>> Now, I could make each function a title, like
>>
>> function_name(params):
>> **********************
>>
>> The docstring
>>
>> But I don't think I can get that to look like I want, even with
>> fancy CSS.
>
> What do you want it to look like?

I'm looking for something vaguely like the Python reference manual.  I 
like the reference manuals for the most part, except they don't have 
very good indexes (which is something I really look forward to with 
docutils/reST).

>> Not to mention that I don't know at what level (h1, h2, h3, etc)
>> the function definition will be -- it's largely orthogonal to other
>> structure.  Hmm... what I'd really like is a directive, like:
>>
>> .. header:: function_name
>>
>> That would create an invisible sort of header, where it shows up in
>> the TOC and is a link target, but isn't otherwise displayed.  Of
>> course, "function_name" always the name of the target, I've been
>> using "ClassName.function_name".  So something like:
>>
>> .. header:: function_name
>>    :anchor-name: ClassName.function_name
>>
>> Anyway, that's my initial thought.  Maybe there's a different way to
>> do this.
>
> I don't think this is a good approach.  It smells like a kludge: too
> single-purpose to be worthwhile, and very magical.  How would this
> translate into elements in the doctree?  The doctree must remain
> self-consistent and style-free (as much as possible).
>
> Although I still suspect you're letting style dictate structure, I'll
> try to help you out.  But we must recognize that there are limits to
> reStructuredText, beyond which we have to consider alternatives.
> ReStructuredText is aimed at ordinary documents; it's not suitable for
> some really creative graphic design exercises, and I don't think it
> should be.

This is, or is supposed to be, the quintessential reStructuredText 
document -- a programmer's reference.  If the doctree is nice, then 
with a little XSL or what-have-you anything is possible (though not 
necessarily easy even then).  But the preprocessor already feels like a 
kludge, and adding a postprocessor feels even worse.  But then I'm 
anti-XML, so I'd feel that way ;)  I prefer event-driven to a tree 
representation, but whatever.

And layout does really matter -- that's a big part of why I don't like 
the output of pydoc.  I want the documentation to look right both in 
the source and in the generated documentation.  It's not an 
unreasonable goal, and I don't think a difficult goal either.

> It seems that you're looking for finer-grained selectability, to be
> able to more precisely target styles.  Currently we have two extremes:
> overly broad (a <div> element surrounds every section, but different
> "types" of sections are not distinct from each other), and overly
> precise (each <div> section element has a unique "id" attribute, which
> *could* be used in the stylesheet, but it would be a manual pain).
>
> Perhaps the "topic" directive would suit your purposes.  See
> <http://docutils.sf.net/spec/rst/directives.html#topic>, and note that
> topics cannot contain subsections or subtopics.  Currently, topics
> don't show up in the table of contents, but that could be remedied
> with a new option to the "contents" directive.

Yes, topics look good.  I just tried using them, and with a little CSS 
tweaking they seem alright.  Though because of the use of <p> tags for 
the title and body, the function title and parameter line is separated 
from its docstring, which I would prefer not to have.  I haven't seen 
anything that lets you change the space between paragraphs with CSS, 
which I've wanted to do often...

> Docutils uses an optional "class" attribute on all elements, which is
> carried all the way through the HTML writer.  The class attribute can
> contain multiple values (space-separated).  A new directive could be
> added that adds a class value to the enclosing element, and this class
> could be selected in the stylesheet.  If the section *containing* the
> specialized function sections is given a class, say
> "function-container", the stylesheet could contain a style like this::
>
>     div.function-container div { ... your styles here ... }
>
> I'll add these to the to-do list.  Contributions are welcome!

Yes, that would work nicely, because then I wouldn't have to monopolize 
topic:: for function definitions.  I still haven't looked at the 
internals of the parsing, but I'll try to look into it more -- it might 
give me some insight into how the extractor should work as well.

   Ian

Ian Bicking wrote:
> 
> On Wednesday, January 29, 2003, at 02:16 PM, David Goodger wrote:
> >> Now, I could make each function a title, like
> >>
> >> function_name(params):
> >> **********************
> >>
> >> The docstring
> >>
> >> But I don't think I can get that to look like I want, even with
> >> fancy CSS.
> >
> > What do you want it to look like?
> 
> I'm looking for something vaguely like the Python reference manual.  I
> like the reference manuals for the most part, except they don't have
> very good indexes (which is something I really look forward to with
> docutils/reST).

We discussed this issue a couple of weeks back, but what I'm
planning to do for my index entries is to label them as
inline targets (or explicit markup targets tied to inline
targets) and have a separate writer that can extract them
into a usable index.

	--Mark

On Thu, 2003-01-30 at 09:52, Mark Nodine wrote:
> > I'm looking for something vaguely like the Python reference manual.  I
> > like the reference manuals for the most part, except they don't have
> > very good indexes (which is something I really look forward to with
> > docutils/reST).
> 
> We discussed this issue a couple of weeks back, but what I'm
> planning to do for my index entries is to label them as
> inline targets (or explicit markup targets tied to inline
> targets) and have a separate writer that can extract them
> into a usable index.

Oops, I meant table of contents.  But I want an index too!  I want it
all! ;)

It seems it would be very easy to start with an index made up of all the
targets in the document.  I noticed some notes on something like
`word`:index: which would also be possible, but probably more thorough
than I'd use in programming documentation.  

-- 
Ian Bicking           Colorstudy Web Development
ianb@...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241