RFE: Add mechanisms for customizing automatic section numbering

[mwoehlke]

I'm working on a document (more particularly, I'm [ab]using sphinx to write a novel) that has rather particular requirements for section names:

• Some sections should not be numbered.
• Some sections are numbered, but must have specific (non-changing) text before the number.
• Some sections should be numbered with Roman numerals.
• Numbering should restart between groups of sections with different requirements.

Right now, Sphinx only supports the last item. I would like to see automatic section numbering improved to support these features.

In particular, my TOC looks like:

• Foreword
• Prologue
• Chapter 1: Raining Cats and Dogs
• Chapter 2: Other Silly Metaphors
• ...
• Appendix I: Etymology of Animal Names
• Appendix II: Origins of Filler Text
• Glossary

As chapter numbers are subject to change, I would really prefer to use automatic numbering rather than hard-coding everything into the actual headings. I can almost get there with Sphinx's current features; what I am missing is the ability to add prefix text to the section numbers (needs to be per toctree directive), and ability to choose the number style (likewise). The latter in particular seems like it really ought to be added as a feature, since someone might want to use other numbering styles depending on their language.

[mwoehlke]

I have an approach that "works for me", here. However, it only supports HTML builders for now, and on further consideration, is probably not the best approach. The "right" way to do this is possibly to have the user supply a Python function that turns the number tuple into a string, with some way to select different convertors or pass through an identifier (which the user specifies per toctree) to the convertor.

[jessetan]

@mwoehlke Suggestion: in your number_convertor also add a letters option that uses a function like:

def number2letter(n):
    l = ''
    if (n > 26):
        l = chr(64 + (n - 1) / 26)
    l += chr(65 + (n - 1) % 26)
    return l

This gives A, B, C, etc for the first 26 chapters, followed by AA, AB, AC etc, up until ZZ for the 702nd chapter.

[mwoehlke-kitware]

@jessetan, what about numbers and/or letters in other languages?

In my current approach, I abandoned trying to build in such cases, and instead I just invoke a user-supplied function. That way the user can implement whatever code they need.

[jessetan]

Yes, that is indeed much more flexible.
For implementation in Sphinx, I'd argue that numbers, roman numerals, and letters are the most common uses of section numbering and users would benefit from a single option that switches between these, without requiring them to write their own Python function.
They also map nicely to the counter types available in LaTeX.

[mwoehlke-kitware]

...but in what combinations? The user-supplied function takes the stack of section numbers. How do I express that I want 1.II.A vs. A.1.II. How do I express — per level — if I want upper- or lower-case? Trying to provide "defaults" beyond the built-in 1.1.1 quickly grows into a geometrical explosion of possibilities, at which point, the value vs. just forcing the user to provide the complete function falls off sharply.

(That said, I could see having a 'number to letter' utility function, as per your previous comment, in Sphinx, that users could use in their supplied numbering function. I don't know that I'd bother with one for Roman numerals, though; the value vs. the one you get from import roman would be negligible.)