Re: [Docutils-develop] Headers

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

[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