Modifying Sections#
It’s often the case that you’ll want to organize the contents of a tab (see the previous walkthrough on adding a new tab). We’ll be covering the following scenarios:
How to add a new section
How to add a sub-section (section nested in a section)
Exploring the left navigation layout#
For this walkthrough, we’ll be using the layout of the Tab_2 tab to understand how sections are organized.
The four “subject” documents with the arrows next to them are “top-level documents”.#
This layout relates to the file tree rooted at sphinx-documentation-demo/docs/tab_2:
📦tab_2
┣ 📂subsection_1
┃ ┣ 📜index.rst
┃ ┣ 📜subsubject_1.rst
┃ ┗ 📜subsubject_2.rst
┣ 📂subsection_2
┃ ┣ 📜index.rst
┃ ┣ 📜subsubject_3.rst
┃ ┗ 📜subsubject_4.rst
┣ 📜index.rst
┣ 📜subject_1.rst <- top level
┣ 📜subject_2.rst <- top level
┣ 📜subject_3.rst <- top level
┗ 📜subject_4.rst <- top level
The subjects with the arrows are “top level documents”.
Organizing Top-Level Sections#
So how does Sphinx know how to organize those top-level documents into Section 1 and Section 2?
Let’s look at sphinx-documentation-demo/docs/tab_2/index.rst:
1.. toctree::
2 :maxdepth: 1
3 :caption: Section 1
4
5 subject_1
6 subsection_1/index
7 subject_2
8
9.. toctree::
10 :maxdepth: 1
11 :caption: Section 2
12
13 subject_3
14 subject_4
15 subsection_2/index
There are two toctrees contained in this index.
Each toctree corresponds to a section within Tab_2
The name of the section is determined by the
:caption:role (see the two lines highlighted in yellow)
subject_1 and subject_2 belong to the first toctree (“Section 1”)
subject_3 and subject_4 belong to the second toctree (“Section 2”)
Adding New Section#
A quick way to demonstrate adding a new section is by adding a new toctree to the index at docs/tab_2/index.rst.
We will also move an existing document to the new section.
Change the toctrees in docs/tab_2/index.rst to the following:
1.. toctree::
2 :maxdepth: 1
3 :caption: Section 1
4
5 subject_1
6 subsection_1/index
7 subject_2
8
9.. toctree::
10 :maxdepth: 1
11 :caption: Section 2
12
13 subject_3
14 subject_4
15 subsection_2/index
16
17.. toctree::
18 :maxdepth: 1
19 :caption: My New Section
20
21 subject_4
The last toctree is the new one added for this demonstration.
The first highlighted line will be the title of the section.
The second highlighted line will be the document (
subject_4) that’s contained in this new section.Notice that you can have the same document in more than one section. Sphinx knows how to link to the same document.
You should notice a new section in Tab_2.#
Adding a New Subsection#
A subsection is nested within an existing section.