Change numbering styles in different parts

[choldgraf]

Describe the problem/need and solution

Sphinx allows you to add numbers to chapters via the :numbered: flag in a TOCtree. In addition, sphinx-multitoc-numbering allows you to continue numbering across parts.

However, many books have an appendix that should both restart numbering and use a different numbering style. A common example of this is:

Introduction

1. First chapter
2. Second chapter
3. Third chapter

A. Appendix 1
B. Appendix 2

It would be useful if people could do two things:

1. Re-start numbering for some parts of their book
2. Choose a different numbering style

Guide for implementation

There's a Sphinx issue that already exists about this: sphinx-doc/sphinx#6614

But perhaps we could implement something via sphinx-multitoc-numbering, for example supporting some extra toctree metadata like:

```{toctree}
:numbered:
:numbered_group:
```

Along with a config like numbered_group_styles = {"group1": "123", "group2": "ABC"}.

I wonder if @mmcky has thought about that possibility?

Tasks and updates

No response

[tavin]

Thanks to executablebooks/MyST-Parser#188 I found a workaround that allows me to build a latex/pdf article with appendix numbered A:

```{role} raw-latex(raw)
:format: latex
```

{raw-latex}`\renewcommand{\thesection}{A}`

I'd like to do this with a raw directive and skip the role definition, but for some reason that doesn't work.

[mmcky]

@choldgraf we did look into this when we were putting together sphinx-multitoc-numbering.

From memory the main issue is there is no real "concept" of this document structure in sphinx so is non-trivial without making assumptions. I think ideally sphinx would support more document structure metadata such as front matter and appendix in the abstract syntax tree so we could leverage that contextual information.

It might be possible to add sphinx-frontmatter and sphinx-appendix packages to add nodes into the AST and then implement visit_ and depart_ methods to treat them in html and latex. (@AakashGfude what do you think about this idea?)

Thanks @tavin on that workaround for LaTeX to override part numbers in the latex/pdf output.

[AakashGfude]

Sounds like a good idea. We can create the facility of having a group metadata in toctree which we can use to add custom nodes in the AST, storing the numbering scheme. We can probably implement it in sphinx-multitoc-numbering instead of creating new packages? @mmcky. As we will have to interfere with sphinx-multitoc-numbering functionality.

[mmcky]

🤔 -- interesting, thanks @AakashGfude perhaps we could call it something like sphinx-book-structure and then it could contain structural nodes to boost the information in the sphinx.ast and teach sphinx how to work with the various parts. etc.

[AakashGfude]

@mmcky Hmmm, that can work. Let's start implementing it soon and see how we go. Should we put this issue in the Bug reduction drive? That issue is turning out to be a repository of things to focus on 😅

[michaelosthege]

+1 for this enhancement

Selectively turning headline numbering off is important for writing scientific articles (jb-article).

It would be great to give an example _toc.yml for a typical article structure:

Abstract
Abbreviations
1. Introduction
2. Methods
3. Results & Discussion
Acknowledgements
References

Please let me know if this is already possible with sphinx-multitoc-numbering because all my attempts so far ran into Table of Contents file is malformed: Unknown keys found: {'numbered'}.

[mmcky]

I guess the real question here is whether this should be implemented here as a package or if we should look at pushing a contribution upstream to add these document style structures in sphinx. I am inclined to leave it as an extension approach given we would have access to _toc.yml metadata such as jb-article and jb-book etc. to infer better context.

[mmcky]

Please let me know if this is already possible with sphinx-multitoc-numbering because all my attempts so far ran into Table of Contents file is malformed: Unknown keys found: {'numbered'}.

@michaelosthege currently this is not available in sphinx-multitoc-numbering. It was designed to build a compatible table of contents based on the various _toc.yml structures available in jupyter-book and the multiple toc tree objects used in jupyter-book (cc: @AakashGfude)

[michaelosthege]

This week I managed to render a pandoc-Markdown into DOCX and PDF that look really good. For the PDF I even got partially numbered headings working: https://boisgera.github.io/pandoc/markdown/#heading-identifiers

Maybe one can adopt their approach?

---

Are there examples (tests?) where _toc.yml is bypassed? I looked into the code and it seems to be mostly a big codebase parsing the YAML and making a dict of objects from it. I'd much rather create those TocTree objects myself, interacting with their API directly and having access to attributes that are not supported in the _toc.yml "schema". (Such as the numbered/unnumbered thing.)

[giswqs]

I am also looking for a way to restart the numbering for different parts of the book

[michaelosthege]

@giswqs you can do it like this:

In the MyST markdown files:

% Creates a custom role for inserting raw latex
```{role} raw-latex(raw)
:format: latex
```

{raw-latex}`\section*{Acknowledgements}`
{raw-latex}`\addcontentsline{toc}{chapter}{Acknowledgements}`
Here comes the content.

{raw-latex}`\section*{Published work}`
{raw-latex}`\addcontentsline{toc}{chapter}{Published work}`
Here comes the content.

The * makes it a non-numbered section (I think) and the \addcontentsline adds it to the TOC as a chapter.

In _toc.yml I REMOVED two lines according to my git history:

format: jb-book
root: index
options:                     👈 remove this line (unless you set other options)
  numbering: true            👈 remove this line
chapters:
- file: 0_Prefix/prefix.md
- file: 1_Introduction/introduction.md

[giswqs]

@michaelosthege Thanks for the tricks. It would be better if jupyter-book can officially support this so that we only need to modify _toc.yml without hacking myst content.