Sphinx: Implement parts (of book)

[mixmastamyk]

Hi, I have an website/ebook I'm working on with parts, e.g.:

Part I: Basics

1. Ch. One
2. Ch. Two

Part II: Intermediate

1. Ch. Three
2. Ch. Four

Part III: Advanced Stuff

1. Ch. Five

etc. But can't seem to figure out how to do it. The toctree caption helps with the title of the first part. If I use several toctrees however they restart numbering from 1. How can I use one toctree to do this, or perhaps several that can pick up numbering where the last left off? Thank you,

[mixmastamyk]

BTW, I need this and would consider giving a $100 tip (perhaps by Amazon gift card) to get it done. Sorry I can't afford a larger amount.

It might be as simple as implementing an offset parameter for the toctree.

[tk0miya]

As a quick hack, I made a simple extension to resolve this:
https://gist.github.com/25bd52887adea5314fe15f1e3afc0949
(it works only with Sphinx-1.5)

This extension assigns numbers to each sections with following rule:

• treat top level sections as "parts"
• treat second level sections as "sections"
• Do not assign numbers to "parts"
• Assign sequential number to "sections" whole of document

At my local, it seems working.

BTW, we should consider carefully how to support ToC like this case.
I feel my extension is too adhoc to merge sphinx-core.

[mixmastamyk]

Awesome, does this mean my chapters would become parts? That might be hard to do because my book is getting long and would be hard to rearrange.

I wonder if it would be easier to add an :offset: parameter to the toctree, so that it would start numbering at a given number or continue where it left off. So then I could add it to the second toctree to get it to start at the right place.

[tk0miya]

My extension considers first level sections as parts and second level ones as chapters.
I believe this document structure is useful for LaTeX output.
With latex_toplevel_sectioning = 'part', LaTeX builder also considers parts and sections same as my extension.

At this moment, how do you make chapters in your reST? I'd like to see any example.

BTW, your idea, :offset: option is hard to realize in LaTeX output to my knowledge. In addition, we need to consider side effects. for example, duplicated section numbers, skipped numbers and so on.
So I'd like to consider carefully to improve ToC feature in sphinx-core.

[mixmastamyk]

I see, unfortunately I don't have any experience with latex. I keep each chapter in its own .rst file, as they are relatively large. For example:

.. toctree::
    :caption: Part I: Basics
    :maxdepth: 1
    :name: PartI
    :numbered:

    one
    two
    three
    four

Output looks like this:
https://mixmastamyk.bitbucket.io/pro_soft_dev/

In last toctree, I turned off numbering because it resets back to 1.

Would this strategy force me to put every ten chapters (or so) into a single file? That's not practical in my case, the book is already 16 thousand lines and will grow. Thanks again for your interest.

[marco-buttu]

I am also interested in this feature. For my book I solved haking the Sphinx code (it was Sphinx 1.3), and now I have the following structure:

This is the parts toc:

This the chapter structure:

Is this what you would like to have?

I tried the @tk0miya extension (with Sphinx 1.5.2) but it did not produce the same result. Maybe there is something wrong with my project structure. I have one top level index.rst, one directory per part, each one containing its own index.rst (of chapters) and the .rst files of the chapters (one file per chapter):

index.rst
part1/
    - index.rst
    - chX.rst
    - chY.rst
    ...
part2/
    - index.rst
    - chZ.rst

[tk0miya]

I made example for my extension. Could you check this please?
3357.tar.gz

[marco-buttu]

Your example works fine :-) In my book, apparentely with the same structure as your example, I do not get the number of the chapter. It is assigned to the first section of the chapter... I will investigate and I will tell you. Do you think you will add the extension to the other builtin Sphinx extensions? Thank you very much!

[tk0miya]

As I said above, I feel my extension is too adhoc. So I would not like to add it to sphinx-core.

[mixmastamyk]

Hi, yes it works here. However I was hoping for a structure where I could use multiple toctrees with different captions and consecutive numbers. The way you've organized your Parts makes them very important, front and center, so to speak. But for my book the Parts are not the most important part, haha.

[abingham]

I'm looking for similar functionality. I noticed that the ":numbered:" option to toctree accepts an optional integer (i.e. its option spec is int_or_nothing), yet that number seems to not be used. I wonder if the original intent was to let you specify where to start the section numbering for a toctree.

[mixmastamyk]

Agreed, thought of that too, not sure if I wrote it in this bug however.

[mixmastamyk]

I gave up and started using sectnum on the second part instead, though it breaks the numbers for numbered figures. :-/

[thfanning]

I came across this thread looking for a solution to the same issue. Not finding one, I implemented a very simple :continue: option for the toctree directive (#4733). If multiple :numbered: toctrees exist in the same document, the :continue: option will result in sequential numbering.

[mixmastamyk]

Yeah! Hope it makes it in.

[mixmastamyk]

Still need this. Was told a few years ago that a design would have to be decided on. It is technically not hard to do. A pull request with an implementation already exists.

Could someone make a decision please? I'm available to help. ;-)

[yasoob]

Any update on this?

[AakashGfude]

We have implemented a small extension to solve this continuos numbering issue, in which you guys might be interested: https://github.com/executablebooks/sphinx-multitoc-numbering. Thanks, @tk0miya for your code from which it was inspired.
It is based on sphinx 3.1.2. Would love to hear everyone's ideas, bug reports, and feature requests we can make to this to accommodate various numbering patterns and cases.