birkenfeld / sphinx (http://sphinx.pocoo.org/)

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects, written by Georg Brandl and licensed under the BSD license.

Clone this repository (size: 20.6 MB): HTTPS / SSH
$ hg clone http://bitbucket.org/birkenfeld/sphinx/
← Back to results
follow

#326 Add way to reference chapters / sections

Reported by Mark Lodato / marklodato, created 7 weeks ago, last edited unknown.

If you have numbered sections, it would be useful to be able to reference other sections by number, rather than title. For example, :secref:`foo` would be the same as :ref:`Section 4 <foo>`, provided foo was in the fourth section. Often, saying "we'll cover this in Chapter 4" reads much better than "we'll cover this in The Configuration File", especially if the title is long.

Once this is implemented, the title format and maximum depth should be configurable (e.g. only reference up to two levels deep).

I would like to try to implement this as an extension, but I'm not sure how to begin. If someone give me a hint for how to get the section number located at a particular reference, that would be a huge help.

Followers: 1
Status: open Responsible: nobody Type: enhancement
Milestone: none Component: none Version: 0.6.3

Attachments

No attachments added for this issue yet.

Comments and changes

#1

Georg Brandl / birkenfeld
written 6 weeks ago, last edited unknown.

→ Changed status from new to open.

This is already planned for printable output (i.e. LaTeX) -- do you think it's necessary for HTML output as well?


#2

Mark Lodato / marklodato
written 6 weeks ago, last edited unknown.

Well, I don't think it's necessary, but it would be nice. I am writing materials for a class, and each chapter is devoted to one day. Therefore, the chapter numbers have meaning. Saying "we'll cover this in more detail in Chapter 4" indicates how far into the future it will be covered, whereas "we'll cover this in more detail in Lists and Tuples" does not convey such meaning. Ideally, the link "Chapter 4" would have a title attribute saying "4. Lists and Tuples".

While I'm wishing, I would also like this to be configurable. In conf.py, I would like to be able to create a new role with a custom format string and a maximum section depth. For example, say I did the following:

customref.add_role("day", format="Day %s", maxdepth=1)

Now, if I have a reference 'foo' in Section 4.2.3, if I say ":day:`foo`" I will get "Day 4".


Add comment / attachment

Show/hide preview

Verification: Please write the text from the image in the box (letters only)

captcha

Is that you, Humanoid? Is this me?