Add way to reference chapters / sections

[shimizukawa]

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.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/326
• Originally reported by: Mark Lodato
• Originally created at: 2010-01-22T02:13:29.442

[shimizukawa]

From Georg Brandl on 2010-01-31 18:27:53+00:00

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

[shimizukawa]

From Mark Lodato on 2010-01-31 19:20:20+00:00

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".

[shimizukawa]

From Georg Brandl on 2013-03-31 13:57:38+00:00

Removing version: 0.6.3 (automated comment)

[tk0miya]

Since Sphinx 1.3, we introduce :numref: role to reference figures and tables using its figure (table) number.
I think it would be good if the role can also refer sections using its number.

[andreacassioli]

HI,
any progress on this issue? Out there there are already some unofficial extensions that replaces the section title with a counter.

[tk0miya]

Not yet. please let me know them.

[andreacassioli]

It is not really an extension, but it works well:

https://github.com/jterrace/sphinxtr/blob/master/extensions/numsec.py

Others have similar approach. I use it regularly and it seems to be OK.

[jason-s]

numsec looks like it replaces all instances of :ref: with the section number. We could really use a :numref: for section numbers.

[andreacassioli]

That sounds very good.

I guess that there should also be a setting to customized the output: should we say Section 1 or Chapter 1? Section 1.2 or Sec. 1.2?