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 > <ol>> 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 <#7934 (comment)>> , 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 😉