Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Improve appearance of table of contents with reST #111

Closed
wants to merge 1 commit into from

4 participants

@rschroll

Tables of contents with reST are currently ugly. (See, e.g., this.) There are several problems; one of them is that the top-level heading is included in the table of contents, even if it is acting as a header. Turning doctitle_xform on fixes that, but makes the next-lower header rise up to <h1>. Changing initial_header_level pushes it back to <h2>.

@rschroll rschroll rest2html: Improve display of Table of Contents
Currently, the top level header appears in the table of contents,
even if it is acting as a header.  Turning doctitle_xform on
fixes that, but makes the next-lower header rise up to <h1>.
Changing initial_header_level pushes it back to <h2>.
68998a7
@homeworkprod

I support this change. The document is unnecessarily obfuscated by that additional, unintended level of nesting.

Temporarily doing without section numbering is a poor workaround for larger documents, especially with repeating sub-heading titles.

See http://docutils.sourceforge.net/docs/user/config.html for details on the standalone reader's doctitle_xform flag.

@jdavid

+1

@gjtorikian
Admin

@rschroll Is this still a problem?

@rschroll

The appearance of the table of contents has improved, but this problem still exists. See for example this document. There's no need to have a single top-level list item with the title of the document. I'd rather have all of the section headers be the top level of the list and not have the title appear in the contents at all.

@gjtorikian
Admin

I agree that that would make more sense.

I'm not an RST expert, but it seems like that's by their design, though: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

Seems like by simply doing .. contents:: :local: you can achieve what you want.

@gjtorikian gjtorikian closed this
@rschroll

That does it. Thanks for the tip!

@gjtorikian
Admin

Sorry for taking a year to get to this! :tada:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 28, 2012
  1. @rschroll

    rest2html: Improve display of Table of Contents

    rschroll authored
    Currently, the top level header appears in the table of contents,
    even if it is acting as a header.  Turning doctitle_xform on
    fixes that, but makes the next-lower header rise up to <h1>.
    Changing initial_header_level pushes it back to <h2>.
This page is out of date. Refresh to see the latest.
Showing with 2 additions and 1 deletion.
  1. +2 −1  lib/github/commands/rest2html
View
3  lib/github/commands/rest2html
@@ -24,7 +24,8 @@ SETTINGS = {
'file_insertion_enabled': False,
'raw_enabled': False,
'strip_comments': True,
- 'doctitle_xform': False,
+ 'doctitle_xform': True,
+ 'initial_header_level': 2,
'report_level': 5,
}
Something went wrong with that request. Please try again.