1

I'm improving some technical docs (Sphinx) and would like to include the contents of an RST file in multiple places; however, in doing so, that RST file is being added to the TOC multiple times. How can I include the file where I want but only reference the section in the TOC once?

Here's what the index.rst file looks like:

Documentation
=================
.. toctree::
   :maxdepth: 4

   ../path/to/releasenotes.rst
   ../path/to/general_api_usage.rst
   main_content.rst

Next, here's main_content.rst:

============
Main Content
============

These docs reference:
- :ref:`section-1`.

- :ref:`section-2`.

- :ref:`section-3`.

- :ref:`section-4`.

.. include:: section1.rst
.. include:: section2.rst
.. include:: section3.rst
.. include:: section4.rst

"Section 4" is a reference table; I'd like to include it in "Section 2", for example, but also keep it at the bottom of the docs like an appendix.

Here's what section2.rst looks like:

.. _section-2:

This is Section 2
********************

.. include: section4.rst

Some other Section 2 content.

And finally, what section4.rst might look like:

.. _section-4:

This is Section 4
********************

+------------------+-------------------------+
| Heading          | Heading 2               |
+==================+=========================+
| This is what I   | want to reference       |
+------------------+-------------------------+
| in other rst     | files.                  |
+------------------+-------------------------+

When I do this, my table of contents includes "Section 4" twice. Any insights? Thanks!

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Keon
  • 31
  • 1
  • 3
  • Is it possible to remove the section heading from the document `section4.rst` and if needed move it to the including documents? Or are there actually more headings than show in the example? – sinoroc Nov 22 '19 at 20:23
  • 1
    Thanks @sinoroc. This was really helpful. I accomplished what I was hoping to do thanks to your suggestion. – Keon Nov 22 '19 at 21:38

1 Answers1

2

Thanks to a suggestion from @sinoroc, I've come up with a solution:

I removed the following from section4.rst, and kept only the table:

 .. _section-4:

 This is Section 4
 ********************

I added it to the top of a new file, appendix.rst, and added a reference to section4.rst:

 .. _section-4:

 This is Section 4
 ********************

 .. include:: section4.rst

I then modified my main_content.rst to refer to appendix.rst instead of section4.rst.

My main learning point: The TOC reflects the headings in the referenced files.

Keon
  • 31
  • 1
  • 3