Allow including documents multiple times (using different section numbers)

[felixvd]

This issue might be an x-y problem, and there might be a better solution. Let me explain what I am trying to do first.

I want to build multiple manuals that have sections in common. Imagine modules with the same safety warnings, for example. I would like to include the common sections in multiple places, so they can be reused. However, I have been stumped on how to include these files properly.

My understanding is that Sphinx is not intended for multiple manuals in one folder (as noted by @tk0miya here), but copying the content would be bad, and this SO question implies that my use case (and confusion) is not rare, and people have come up with many different workarounds.

I thought that the best solution would be a single source directory containing all the content, and subfolders with a conf file declaring the top-level index of each manual. However, I realized that each node can only have one section number, which will be displayed wherever it is included. For files that are included in multiple locations, one of the numbers will usually be wrong. Here is a minimal example producing this output:

I have considered these alternatives:

• Using the include directive, but this breaks relative image links
• Symlinking, but this has the same drawbacks and more (not platform-agnostic, seems hacky and not scalable)
• Using tags to disable section numbering, but the doc states that it's not possible
• Intersphinx, but this does not allow including whole files
• Ditching Sphinx and using DITA Open Toolkit instead, but this would sacrifice tools like autodoc/autoapi

It would be great if Sphinx assigned the section number on-the-fly, depending on the position in the ToC hierarchy. More generally, it would be great if managing multiple manuals/documentations with overlapping contents was supported -- it surprised me that all documents are compiled, instead of only the ones that are needed for root_doc.

My questions are:

• Is there an accepted method to achieve what I am trying to with Sphinx, and what is it?
• How much development effort would it take to fix the section numbering issue?
• How much would it take to support multiple manuals built from the same source?

I am open to investing some cycles into contributing back, but I would first like to make sure that the direction is good and that changes can be merged down the line. Sponsorship or setting a bounty are an option as well. Thanks for discussing.

Related:

• https://github.com/sphinx-doc/sphinx/issues/5145 mentioning problems with latex, and the comment by @tk0miya mentioned earliear
• https://github.com/sphinx-doc/sphinx/issues/6614 deals with numbering, but not this problem
• This SO question

[amotl]

Dear Felix,

we are also currently looking into this. I think another SO discussion may revolve around the same topic ^1. Did you find out about any known solutions, maybe in the form of Sphinx extensions?

Specifically, we are looking into creating index pages to bundle multiple individual files from our release notes together. Because each single page has the same structure (and headings), a strategy like

.. include:: 5.0.0.rst
.. include:: 5.0.1.rst
.. include:: 5.0.2.rst
.. include:: 5.1.0.rst

also does not work out:

Warning, treated as error:
../docs/appendices/release-notes/5.0.0.rst:139:Duplicate target name, cannot be used as a unique reference: "breaking changes".

It is slightly different, but I think still reflects a very similar use case, and, most importantly, bumps into the same wall. Please correct me if you think I am wrong, so I will divert my post to a different issue instead.

In any case, also because you explored many options already, I thought it would be a good idea to reach out to you, in order to find out if you may have found another solution in the meanwhile, or to collaborate on some Sphinx extension, which aims to do DWIM for our shared use cases.

With kind regards, Andreas.

[amotl]

It looks like the MyST include directive offers a heading-offset directive option, which can

offset all the heading levels [of the included page] by a positive integer number.

-- https://github.com/executablebooks/MyST-Parser/issues/262#issuecomment-1449474949

[felixvd]

Hi Andreas,

Thanks for your response. If I understand correctly, you are trying to include multiple similar documents with similar structure in one file, and the error occurs because headings/references are duplicated. That does seem like a different issue.

The issue I have is that linking the same page in different sections causes it to have incorrect section numbers. I assume because it is the same object at each location in the tree and the section number is overwritten. This does not keep the project from building, unlike the issue you described.

I have found no other workarounds for this outside of the ones described in the first post. In my own project I duplicated the content for now.

I think a solution that links the page without changing the section number would be ideal, but I have not found the time to read through this source code and estimate if a change is feasible. I was hoping for a maintainer to weigh in first.

That said, I wonder if your issue can be solved by A) placing each include under its own header, e.g.:

# 5.0.0 Release Notes
```{include} 5.0.0.rst
:heading-offset: 1

5.0.1 Release Notes

:heading-offset: 1

and offsetting the headers as you linked.

Or B) reducing the [depth of header anchors](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors)

Or, if you use them, C) making sure that [explicit targets](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#creating-explicit-targets) are unique. E.g.:

(5-0-1-breaking-changes)=

Breaking Changes

instead of `(breaking-changes)=` .

[amotl]

Hi Felix,

apologies for hijacking this discussion with my wrong assumptions. Nevertheless, thank you very much for your suggestions on our project, I will try them tomorrow.

In order to eventually help out a bit on your issue, which will probably be a bit harder to resolve, I've at least tried to approach the repository and problem on behalf of https://github.com/felixvd/sphinx-toctree-numbering-example/pull/1.

If you like, we can go on with the discussion there, and eventually report back here, when anything sensible may turn up.

With kind regards, Andreas.

[amotl]

Hi again,

do you think after that we've discovered at https://github.com/felixvd/sphinx-toctree-numbering-example/pull/1#issuecomment-1661392268, that it seems to be a general determinism issue, that those two other issues may be related in one way or another?

• https://github.com/sphinx-doc/sphinx/issues/2944
• https://github.com/sphinx-doc/sphinx/issues/3007

With kind regards, Andreas.

[felixvd]

I think those issues are very likely related, but there might also be multiple causes. Good find.