#78 Table of Contents + cross-reference section headings

v3.1
open
Epytext (19)
5
2008-02-11
2008-02-11
No

For documentation with many headings and sub-headings, it would be useful to generate a Table of Contents at the top of the page.

Also, in the same vein, it would be very handy to be able to cross reference section headings.

def example():
"""

Section 1

This is a paragraph in section 1.

Section 2

This is a paragraph in section 2. for more information on something else, check out L{Section 1}.
"""
#[...]

Discussion

  • Chad Dombrova

    Chad Dombrova - 2008-02-11

    Logged In: YES
    user_id=1857838
    Originator: YES

    in retrospect, i see a little more explanation might be necessary:

    about the Table of Contents:
    perhaps a new keyword ( @TOC ? ), which would generate a set of hyperlinks of all sections in the current doc string. this would provide the ability to quick jump to any section and also give the user an overview of the documentation.

    about creating links to section headings:
    perhaps this functionality would work as an additional modifier for cross referencing. i can see how the example that i gave above would confuse the current search method, but perhaps some modification to the syntax would make it more viable:

    current behavior -- jumps to the top of the docs for myObject:
    L{myObject}

    new behavior -- specifies which sub-section to jump to :
    L{myObject, 1.1.3}

    jump to the given section of the current object:
    L{,2.1}

     
  • Edward Loper

    Edward Loper - 2008-02-25

    Logged In: YES
    user_id=195958
    Originator: NO

    It's worth noting that both of these pieces of functionality are available if you use reStructuredText as your markup language.

    Adding links to section headings in epytext shouldn't be too hard.. If epytext were adjusted to add an anchor whenever it writes a section heading, then you could just reference those as-is using U{name <#anchor-key>}. The anchor could be formed, e.g., by replacing any sequence of non-alphanumeric characters with a dash. So for your example, where the section heading is "Section 1", you would reference it like U{this <#Section-1>}. Of course, this could cause conflicts between anchors if a section has the same name as a variable; but there's already the possibility of anchor conflicts e.g. if you define "foo" and "Foo" (since anchors are case insensitive).

    As for adding table of contexts to epytext -- I'd have to think about it. Epytext doesn't really have any syntax for defining new block-level elements. And "@foo" gets translated to a field list, which wouldn't be appropriate for various reasons. The most likely solution would be something like the existing G{...} for adding graphs -- this uses an inline markup format, even though graphs are really block elements; and if it find a G{...} used inline, it breaks the containing block element in half. We would have to decide what colorizing tag to use, though, and they're a fairly precious commodity -- we only have 26 prefix letters to work with! :)

     

Log in to post a comment.