Is there a way to start the toctree numbering in the page ?

[12rambau]

I have the following page in my documentation : https://docs.sepal.io/en/latest/cookbook/area_estimation.html#introduction

There are definitelly to many section to easily navigate tin the page but that's ok with the right side panel. I would like to use numbered headings in the page but not in the rest of the documentation.

making my numbering starting to 1 in this page instead of 1.1

At the moment what I did is just to add the :numbered: to the calling toctree (https://github.com/openforis/sepal-doc/blob/master/docs/source/cookbook/index.rst) but this is not the exact behavior I'm looking for. Do you have any idea if it's possible ?

edit

here is a picture for better describe my problem what is my objective:

[jorisvandenbossche]

Interesting question! I think the main problem is that sphinx sees the whole project as one big document, so the :numbered: flag in toctree is for the full document-wide table of content, and not for "within-page" sections.

But to me it certainly makes sense to want to number subsections per page. I am not sure sphinx supports this out of the box, though. There seems to be the .. sectnum:: docutils directive you can add to a page, but sphinx seems to explicitly not support that directive (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html?highlight=sectnum#directives) (still might be worth a try)

[12rambau]

I gave it a try and the problem is actually the same. The h1 title is considered as 1 so my page numbering is all 1.XX.

Obviously the solution must be a sphinx trick to stay consistent with the pdf generated file.

[choldgraf]

yep - I think this is not built into Sphinx (in fact Sphinx assumes that what we have in the right sidebar is actually in-line with the left sidebar). We'd need to manually modify the right sidebar numbers in the theme.

[jorisvandenbossche]

So if we would want this feature (number the sections within a page, but that would only be for the html output), we would need to inject those numbers when generating the html for the toc (generate_toc_html) ànd edit the html of the main body content.

For the toc html, should be possibe with beautifulsoup (we already add CSS classes with increasing number recursively). But to also do this for the main content sounds a bit more complicated?

[choldgraf]

IMO starting with the right TOC would be a nice first step if @12rambau agrees

[12rambau]

what should I agree to ?

[choldgraf]

Do you agree that it would be useful to have the right sidebar adopt the numbering behavior you propose, but not the in-page headers. (because that might be a longer fix)

[12rambau]

that would clearly be a super fancy first step

When you use a documentation that refers to paragraph number you search for it in the sidebar not by scrolling in your page (or at least I don't)

[12rambau]

TBH I'm not sure we want to implement it in the end. It would mess up with other build (numbering will not be consistent with epub and/or pdf) and as the secondary sidebar is well designed, it's quite easy to find back what you need.

I'll tag it as a wontfix and close it for now.