Custom section numbering (Letters, numbers)

[yves-chevallier]

I have written this Stackoverflow question which also explain this feature request.

Goal

The goal is to customise the toctree numbering method. So use i., ii, ... for frontmatter, 1, 2, 3.1.2 for the content and A., A1, A1.1, B1.2 for the appendix.

By looking at the code, it seems it is easy to add a kludge on the _walk_toc method located in the TocTreeCollector class. However I don't see how I can easily extend this class.

The goal would be to add .. toctree:: directives the options :numbering-format: letters

Considerations

Before I try to implement this feature, I would like to get some feedback. Perhaps it is already possible to do this in a different manner.

[tk0miya]

+1 Reasonable. But I don't know best way to represent it in reST document. I feel :numbering-format: is functional and command-like form. I prefer to use more natural and semantic keywords for it. For example, :class: appendix, .. appendix:: or other forms are better to me.

[mmcky]

hey @yves-chevallier +1 for this feature. I am looking at ways to support frontmatter, appendix and backmatter in the jupyter book project which is powered by Sphinx. I have been playing around with a few different ideas but I like your approach to a numbering style proposed here.

Do you see a project being organised with multiple tocs for specifying the different styles in the index.rst (and presumably if a toctree references another toctree the style or class would be inherited from the top level toc)?.

I was thinking something along the lines of the frontmatter in a toctree with a frontmatter class added to all child documents. But would need to think carefully about the inliner for LaTeX output to ensure we can map to those document components etc.

.. toctree::
   :frontmatter:

   preface

and then standard chapter style listing

.. toctree::

   chapter1
   chapter2
   chapter3

and then appendix in another listing

... toctree::
    :abstract:

   abstract1

an alternative idea is also documented here but it is a bit more clumsy having a single toc with listings of documents based on type like frontmatter

@tk0miya love your work on Sphinx. Thank you!

[yves-chevallier]

@mmcky I had exactly the same request for my project (https://github.com/heig-tin-info/handout) and I wrote a small extension available here:

https://github.com/heig-tin-info/handout/blob/master/extensions/appendix.py

[mmcky]

thanks @yves-chevallier

[tk0miya]

I prefer the idea to add a new directive appendix to Sphinx as another version of toctree directive. I don't know frontmatter and backmatter directives are also needed or not. But they are also acceptable for me. (TBH, I don't know what is "backmatter". So I can't decide it correctly).

[mmcky]

thanks @tk0miya -- I think a specialised TOC might be a nice way to go. I typically think of frontmatter, backmatter etc. from a LaTeX / Book perspective which usually defines each as:

1. Frontmatter
   • Half-title
   • Empty
   • Title page
   • Information (copyright notice, ISBN, etc.)
   • Dedication if any, else empty
   • Table of contents
   • List of figures (can be in the backmatter too)
   • Preface chapter
2. Mainmatter
   • Main chapters
3. Appendix
   • Some subordinate chapters
4. Backmatter
   • Bibliography
   • Glossary / Index

As a general rule backmatter usually behaves like frontmatter in terms of style (i.e. no numbering for chapters etc.) so it may not be necessary. I also know Sphinx has Bibliography and Index support already as directives. I might be able to try and prototype something in the next couple of weeks. @yves-chevallier would you mind if we draw some inspiration from your example?

[yves-chevallier]

Traditionally in a book, you have the fronmatter which has roman page numbers and the titles don't appear in the TOC : Table of content, List of tables, List of figures, List of equations, Abstract... Then you have the main content called in LaTeX mainmatter. Eventually, you have the backmatter in which the titles (sections) are usually not numbered : Glossary, Index, References... The appendix is usually part of the backmatter with title numbered with letters Appendix A, A1, A1.2... B....

In Sphinx, usually all TOCs in the index.rst are visible on the HTML output as independent Tocs which is great in my project (visible here https://heig-tin-info.github.io/handout/) I have 3 .. toctree::: Content, Appendix and Backmatter. In my case the appendix is similar to the .. toctree::, but use letters to number the sections.

In LaTeX as sphinx doesn't generate the table of content, all TOCs are gathered under the same table of content which is acceptable in my case.

[mmcky]

thanks @yves-chevallier I have seen that style commonly used also. I guess this highlights the need for flexibility so authors can choose a style for frontmatter, backmatter etc. I guess the what would be really useful is to have the different parts of a document identified / grouped in the sphinx abstract syntax tree (AST) and then a style can be applied to each in a flexible way as this issue suggests with styles.

I am currently doing some work with the executable books project looking at closer harmony between html and latex for the book context. It would be great to support other structural elements such as Parts as well.