Toctree `numbered` option doesn't create <ol> element

[ArtFlag]

Describe the bug When building HTML, the toctree numbered option doesn't create <ol> element but instead, keeps an <ul> and add a number to the title of the linked pages.

To Reproduce

.. toctree::
   :maxdepth: 1
   :numbered:

   page1.rst
   page2.rst

Gives

<ul>
<li class="toctree-l1"><a href="page1.html">1. My title</a></li>
<li class="toctree-l1"><a href="page2.html">2. My other title</a></li>
</ul>

That also creates styling problems like have a bullet in front of numbers.

Expected behavior

Semantically, wouldn't it be better to get:

<ol>
<li class="toctree-l1"><a href="page1.html">1. My title</a></li>
<li class="toctree-l1"><a href="page2.html">2. My other title</a></li>
</ol>

Environment info

• OS: macos
• Python version: 3.7.5
• Sphinx version: 3.1.1

[tk0miya]

Is it able to assign sub-section numbers? If available, I can accept the change if anybody sends us a PR.

[ArtFlag]

Using :maxdepth:2 I get the subsections but numbered the same way: use an ul and add a number to the text itself.

[tk0miya]

This is an example that uses :numbered: and :maxdepth: 2 option and rewritten <ul> to <ol> manually.

I still did not understand how to show the number of sub-sections. If my understanding correct, <ol> does not support nested numbers.

Anyway, there are a lot of works to switch <ul> to <ol>. There might be many side-effects to change it. So I think discussion does not change the implementation. I'd not like to work for this for now.

[dkter]

@tk0miya it's possible to customize the numbers in an ol:

ol {
  list-style: none;
}

ol>li:before {
  content: attr(seq) ". ";
}

<ol>
<li class="toctree-l1" seq="1">
    <a href="page1.html">My title</a>
    <ol>
        <li class="toctree-l1" seq="1.1"><a href="page1.html">My subtitle</a></li>
        <li class="toctree-l1" seq="1.2"><a href="page2.html">My other subtitle</a></li>
    </ol>
</li>
<li class="toctree-l1" seq="2"><a href="page2.html">My other title</a></li>
</ol>

[tk0miya]

Really? I can't find the definition of the seq attribute. It seems the latest Chrome does not support it. Additionally, WHATWG defines value attribute to determine the ordinal number of the list-item. But it must be an integer, not dotted-integer. https://html.spec.whatwg.org/multipage/grouping-content.html#the-li-element

[dkter]

(whoops, see edited comment)

It may even make sense as it is to just replace uls with ols and use list-style-type: disc so that the list still reads as an ordered list. HTML elements are meant to represent the document's content, after all.

[tk0miya]

Thank you for the info. Now I understand perfectly. But it is difficult to adopt to Sphinx. There are some 3rd party themes that use only their CSS. So the proposed change requires to them all. I understand using <ol> is more semantic and elegant. But we need to keep compatibility for users. So I'd not like to adopt your idea. Thanks,

[ArtFlag]

In my opinion, that’s a very unfortunate decision. We are not improving Sphinx because of existing themes? What if themes are using some dirty JavaScript to fix the html right now? That would help them a lot.

If we were talking about a core api to deprecate, I would understand, but for theming reasons? 

Maybe we could add a class to the UL at least? 

Jul 23, 2020, 06:17 by notifications@github.com:

Thank you for the info. Now I understand perfectly. But it is difficult to adopt to Sphinx. There are some 3rd party themes that use only their CSS. So the proposed change requires to them all. I understand using >

> is more semantic and elegant. But we need to keep compatibility for users. So I'd not like to adopt your idea. Thanks,

— You are receiving this because you authored the thread. Reply to this email directly, > view it on GitHub https://github.com/sphinx-doc/sphinx/issues/7934#issuecomment-662810577> , or > unsubscribe https://github.com/notifications/unsubscribe-auth/AGD7DZQFQS2KEKPHUG3Z6R3R462UHANCNFSM4OWR3LOQ> .

[tk0miya]

If we were talking about a core api to deprecate, I would understand, but for theming reasons?

Yes. It is also important to keep the compatibility of Sphinx. Have you ever seen https://sphinx-themes.org/? There are many kinds of Sphinx themes. I worry about the proposed change breaks these themes. For example, sphinx_rtd_theme; a one of major Sphinx themes does not use the Sphinx's bundled CSS. It means the change will break all of the documents in RTD. Can you allow that?

What if themes are using some dirty JavaScript to fix the html right now? That would help them a lot.

I'd like to know what theme (or project) doing such a hack. Please let me know an example?

Maybe we could add a class to the UL at least?

It might be accepted if somebody sends us a pull request.

[ArtFlag]

I'd like to know what theme (or project) doing such a hack. Please let me know an example?

I do 😉

[choldgraf]

@tk0miya something that I would find helpful for this is if we could at least add a numbered class to the <ul> items that are numbered. That way we can easily differentiate them from the ones that aren't numbered and apply styling etc.

One place where I'd find this particularly useful is in dealing with the fact that Sphinx doesn't provide chapter-level numbering. E.g. if I have two toctrees like this:

.. toctree::
   :numbered:
   :caption: Chapter 1

   page1

.. toctree::
   :numbered:
   :caption: Chapter 2

   page2

Then In the sidebar this will become:

Chapter 1
1. page1

Chapter 2
1. page2

Which confuses readers because now they see two sections called 1.. I'd like to manually update these so they become 1.1. and 2.1., respectively, but doing so requires knowing which parts of the sidebar are numbered and which aren't. A CSS selector would make this much easier

(obviously a better way to fix this would be to allow propagating section numbers across chapters, but I suspect this will be a longer-term problem)

[tk0miya]

As commented above, I can accept a PR applying styles to each list-items (if enough worthy).

(obviously a better way to fix this would be to allow propagating section numbers across chapters, but I suspect this will be a longer-term problem)

If your goal is assigning numbers to them to 1.1 and 2.1, you can do it with making the nested toctree. No hack is needed.

[choldgraf]

If your goal is assigning numbers to them to 1.1 and 2.1, you can do it with making the nested toctree. No hack is needed.

@tk0miya that is precisely my goal. It is possible to do this with :caption: separators? What folks generally want (from me, anyway) is a left sidebar that looks something like:

Chapter title 1
- 1.1 page 1
- 1.2 page 2

Chapter title 2
- 2.1 page 1
- 2.2 page 2

[tk0miya]

Why using ":caption:seperator? Please change "Chapter title 1" to the title. If you'd like to use:caption:`, it is not supported at this moment.

[choldgraf]

Gotcha - so this isn't possible.

The confusion for our users is that it's quite common for Sphinx HTML themes to include the caption of each toctree in the left sidebar (e.g. the sphinx_rtd_theme does this). Users then end up using those captions to denote "parts" of their book, but expect chapters to share the same linear flow between them. This then triggers two unexpected behaviors for users:

• When they build their HTML, numbering restarts between parts in an unexpected way
• When they build the Latex, the parts all get collapsed into a single toctree with one caption

This isn't how I use Sphinx, but I'm just relaying the mental model that it seems many users have.