Re: [Docutils-develop] Headers

[David G. <go...@py...>]

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