[Doc-SIG] numbered headings in reST

[David Goodger]

[David]
>>> To enable a different type of table of contents, the section titles
>>> should have an extra attribute, such as "auto".

[Dmitry]
>> In the version that I checked in today, that is also implemented.

[David]
> I see that.  It's not exactly what I had in mind though.  It will be
> easier for me to fix it than explain what I mean, so I'll handle it.
>
>> I haven't found a DTD element that would be formatted as a plain
>> list of strings with no paragraph breaks between them. ...
>> Therefore, the contents for auto-numbered sections is now generated
>> as an enumerated list.
> 
> I think the current bullet list structure is adequate; what's
> necessary is some context recognition in the writer.
> 
>> This looks pretty nice, with one exception: the HTML writer doesn't
>> support prefixes for enumerated lists. Thus, the table of contents
>> in HTML looks as your second alternative, and not the first one
>> (which is what I would like to achieve).
>>
>> Do you have any ideas on implementing the prefixes for enumerated
>> lists in HTML? I would really like to have this fixed.
> 
> CSS2 might be able to handle that, but I don't think we need to go
> that route.  Simpler is better, especially since CSS2 support is
> spotty.  Adding some more smarts to the HTML writer should solve it.
> I'll take care of this also.

I've reworked the "sectnum" directive & transform.  Here's how:

* Changed the "contents" directive to produce a "first writer"
  transform.  Now there's no order issues.

* Moved most of the ``docutils.parsers.rst.directives.parts.sectnum()``
  docstring to the documentation:
  
http://docutils.sf.net/spec/rst/directives.html#automatic-section-numbering

* Reworked the ``docutils.transforms.parts.SectNum`` transform's
  ``update_section_numbers()`` method:

  - Simplified calling the method (default parameter values).

  - Removed the "autonum_origtitle" and "autonum_prefix" attributes
    from "section" elements: unnecessarily redundant.  Instead, the
    "title" elements get an "auto" attribute.

  - The section number text is inserted into the title, wrapped in a
    ``<generated class="sectnum">`` element.  We don't actually use
    this yet, but it could be used this to remove the generated text
    if we need to.

* Reworked the ``docutils.transforms.parts.Contents`` transform's
  ``build_contents()`` method:

  - It turns out that we don't need to build enumerated lists; we
    continue to build bullet lists as before.

  - If an "auto" attribute is detected in a title, we add a
    ``class="auto-toc"`` attribute to the bullet list.

  - The generated text is left alone; there's no need to remove it.

* This style makes the bullets invisible::

      ul.auto-toc {
        list-style-type: none }

Take a look at the results:
http://docutils.sf.net/tools/test.html#table-of-contents

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/