Implement sequential numbering for multiple toctrees

[thfanning]

Subject: Implement sequential numbering for multiple toctrees in the same document.

Feature or Bugfix

• Feature (see Implement parts (of book) #3357)

Purpose

Multiple, numbered toctrees in the same document normally start with 1. This simple update allows authors to sequentially number multiple toctrees in the same document, or to specify a specific starting number.

Detail

Multiple toctrees of the form

  Part I
  ======

  .. toctree::
     :numbered:

     foo
     bar

  Part II
  =======

  .. toctree::
     :numbered:
     :continue:

     baz

will result with the heading of baz being numbered as 3. Starting a toctree at a specific number is also possible by giving a positive value as a numeric argument to continue.

A test case is provided, and a unit test is included to verify behavior. The Sphinx documentation has also been updated.

I have only been able to test this with the html builder, but am interested in feedback.

Relates

• Implement parts (of book) #3357

[codecov]

Codecov Report

Merging #4733 into master will increase coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #4733      +/-   ##
==========================================
+ Coverage   83.29%   83.29%   +<.01%     
==========================================
  Files         293      293              
  Lines       39218    39238      +20     
  Branches     5863     5865       +2     
==========================================
+ Hits        32665    32685      +20     
  Misses       5197     5197              
  Partials     1356     1356

Impacted Files	Coverage Δ
sphinx/directives/other.py	91.18% <100%> (+0.17%)	⬆️
sphinx/environment/collectors/toctree.py	90.77% <100%> (+0.22%)	⬆️
tests/test_environment_toctree.py	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9c2fd94...466d4a4. Read the comment docs.

[jfbu]

Regarding the latex builder, I tested briefly (only by way of experiment, I did not look closely at PR) that this does not impact it. One can already obtain the effect by using latex_toplevel_sectioning = 'part' in conf.py, because the default behaviour in LaTeX book class is to number "chapters" continuously, even if enclosed in parts.

By the way for better parallel with html builds, perhaps LaTeX should not number the parts, i.e. use \part*, not \part (but then \addcontentsline{toc}{part}{Name of part} have to be added to latex file).

[mixmastamyk]

One minor question, does it interact properly with toctree captions? I assume it works, however the added docs use headings, while I've used captions in the past for parts of a book. Thanks again.

[thfanning]

@mixmastamyk - yes, captions work properly. The :continue: option simply tracks and/or alters the starting number for numbered toctrees (within the same document). No other manipulation is done.

[mixmastamyk]

Hi, would someone mind taking a look at this pull request? @tk0miya @jfbu

Would be really helpful to be able to write a book with parts in Sphinx. :-D

Thank you,

[thfanning]

I've updated the pull request to resolve conflicts with upstream. Hopefully this will facilitate review and acceptance.

[mixmastamyk]

@tk0miya @jfbu any comments?

[mixmastamyk]

@tk0miya @jfbu any comments?

[thfanning]

@tk0miya @jfbu
I've worked hard to keep this up-to-date with the upstream. This update has only a few new lines of code (mainly in toctree.py). The rest is documentation and tests. Please take a moment to review. Thanks!

[tk0miya]

Sorry for very late response.

We have to design whole of ToC. I can't say what way is better to define better ToC (inc. appendix, indices and so on).

At least, ToC settings and mark-ups should effect to all of HTML, EPUB and PDF (LaTeX) documents. So we need to update this before merging if we choose this way.

[mixmastamyk]

As the extension merely changes the chapter numbers, I'd be surprised it didn't work with other output formats. Is that the case? Has someone tested it and found that not to be working?

[thfanning]

@tk0miya I agree with the need to consider the ToC in an integrated sense. In this case, however, it is entirely up to the user if they want to start numbering at a point other than 1. This PR helps them do that.

Thanks!

[tk0miya]

@mixmastamyk see https://github.com/tk0miya/sphinx_issue_4733

HTML version:

PDF version:

[mixmastamyk]

Thanks, I guess the question is….

• Is the bug in the toctree, where this PR should fix it?
• Or is there a lack of support in the non-html output builders?

If the second, support could be tracked and worked on in separate issues and timeframes.

[tk0miya]

Is the bug in the toctree, where this PR should fix it?

No, this is not a bug. I think this PR introduces a new feature; "part like" sectioning. But this PR is only available for HTML output. So I think this PR should also add the feature to LaTeX builder.

Note: This is not main reason why I'm not merging this now. As I commented above, we have to re-design ToC model of Sphinx. I can't say :continue: option is best way to do that. So we have to discuss what is best form of ToC before implementation.

[mixmastamyk]

It does feel like a design flaw that some builders don't pick up chapter numbers, it means their mechanisms must differ somehow, perhaps numbering needs to be moved up into a parent class.

From the user interface/markup perspective, perhaps a :part: NAME_STRING parameter that combines the current functionality of :caption: and :continue:. (You mentioned removing the sidebar additions from :caption: in the other bug, but I'm currently relying on that.) Perhaps :part: would capture the intent better.

If you need someone to give feedback, I'm available. Where could we go to confer?

[thfanning]

If the second, support could be tracked and worked on in separate issues and timeframes

My understanding is that it is due to a lack of support in non-html builders. Up until now, it's only been by coincidence that they match. All this PR does is modify the section tuple during parsing. Clearly the LaTeX builder doesn't even use it. It's even numbering the un-numbered headings outside of the top-level :numbered: toctrees. Remove the :continue: option from the test case and the LaTeX builder will still get it wrong.

Even though I numbered the "Parts" in the test case (as "Part I" and "Part II"), don't assume those necessarily carry any numeric meaning. For example, the part headings could be "Prologue", "Statics", "Dynamics", "Glossary", "Index", and "Epilogue". Maybe only "Statics" and "Dynamics" should be numbered sequentially (with :continue:) and the others aren't numbered at all.

[mixmastamyk]

Ok, thanks. Wouldn't a :numbered: parameter determine if they are numbered or not? Perhaps section is a more generic name.

[jessetan]

I can't say :continue: option is best way to do that. So we have to discuss what is best form of ToC before implementation.

It would be nice if this PR was used as input for a larger discussion of how toctree is used, see e.g. #4133 about more generic numbering (and lettering) of sections

[thfanning]

It would be nice if this PR was used as input for a larger discussion of how toctree is used, see e.g. #4133 about more generic numbering (and lettering) of sections

@jessetan, I agree. However I would like to see this PR merged first. Then, we could take the numeric secnumber list (was tuple) that is generated and transform it by a custom function into any complex numbering format that is desired (numeric, alphabetic, roman, etc.). Right now, that "function" is simply '.'.join(map(str, node['secnumber'])) in the html writer.

[choldgraf]

It's unclear to me if this is implemented or not - is it? I see that @thfanning closed the issue in a commit but I'm not sure how we can trigger this behavior if we wish

[mixmastamyk]

No, it continues to be ignored.

[thfanning]

I did not intend to close this pull request. We needed to update our internal implementation, but my master branch was so far out of sync with upstream that it was a mess. So I had to force my own master to update. My apologies for not realizing the impact. Honestly, I'm a wiz at Subversion but suck with git.

For my current implementation, see thfanning/sphinx@c2ed5bb. Unfortunately the current branch includes a tweak to equation numbering as well, but the TOC issue is trivial to implement.

[choldgraf]

Maybe @tk0miya could re-open this? I think the issue is an important one because (to my knowledge) this makes sub-sections not have unique numbers (because you'll have a section in two different chapters, each called 1.1, instead of 1.1 and 2.1)

[tk0miya]

Unfortunately, I also can't reopen.