I've got my index file set up like so:
Doc Title
==============================
..toctree::
:maxdepth: 3
:numbered:
:caption: Contents
01_file1
01.3_file2
If the contents are thus...
01_file1.txt:
Level 1 section title
--------------------------------------------
Level 2 section title
............................................
Another Level 2 section title
............................................
and for 01.3_file2.txt:
A third Level 2 section title
............................................
I would expect this because Sphinx treats everything as a single document:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
1.3 A third Level 2 section title
But instead I get this:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
2. A third Level 2 section title
I'm guessing this is because Sphinx (or maybe reST/Markdown?) restarts implicit heading levels with each new text file. Is there a way to get what I actually want?
Quoting the reST documentation...
Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.
The parent file determines the heading level of its included children. To achieve the desired effect, remove 01.3_file2 from index, and place an .. include:: 01.3_file2 in 01_file1.txt at the point where you want to include it.
index:
Doc Title
==============================
..toctree::
:maxdepth: 3
:numbered:
:caption: Contents
01_file1
01_file1.txt:
Level 1 section title
--------------------------------------------
Level 2 section title
............................................
Another Level 2 section title
............................................
.. include:: 01.3_file2.txt
01.3_file2.txt:
A third Level 2 section title
............................................
Results in:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
1.3 A third Level 2 section title
Related
I'm trying to have the following kind of layout in a Sphinx document :
Title
Article 1
Section 1
Article 2
I already saw that no matter what symbols I use to underline or overline the headers, the first appearance of a given heading will determine its hierarchical relation to the others. I.e, the following won't work :
==========
Title
==========
Article 1
---------
---------
Section 1
---------
Article 2
---------
Is there a way to circumvent this, for example by defining an invisible "Section 0" heading between Title and Article 1 with dashes as underline and overline, so that sphinx understands that Sections are greater than Articles, without actually displaying a "Section 0" between the title and the first article ?
I'm trying to do something like this Skipping heading levels in reStructuredText - although I don't really understand the code example they give...
The only ugly solution I found is the following :
=====
Title
=====
-----
\
-----
Article 1
---------
...
The two issues are that it creates a blank gap in the resulting document, and that it inserts a title-less heading in the toctree at the index page (even though it does not do that in the local summary).
I'm using Sphinx's HTML builder with the Read The Docs theme.
I'm trying to build a technical documentation for a project where each page corresponds to a "component", and each "component" may link to "subcomponents" hierarchically, making the whole documentation recursive:
Component 1
***********
Subcomponents
=============
.. toctree::
component_2
component_3
Section A
=========
Subsection a
^^^^^^^^^^^^
Subsubsection i
~~~~~~~~~~~~~~~
However, Sphinx more or less expects the root document to be a dumb ToC, so it gives me the following sidebar structure:
Component 2
Subcomponents
Section A
Subsection a
Subsubsection i
Component 3
Subcomponents
Section A
Subsection a
Subsubsection i
Instead of the one I'd like:
Subcomponents
Component 2
Subcomponents
Section A
Subsection a
Subsubsection i
Component 3
Subcomponents
Section A
Subsection a
Subsubsection i
Section A
Subsection a
Subsubsection i
Edit: For this MWE, I have used a flat directory structure:
_static
conf.py
component_1.rst # root_doc
component_2.rst
component_3.rst
For completeness' sake, I have also tried a directory structure that matches the logical structure (updating toctree links as required), with the same result:
_static
conf.py
index.rst # component_1, root_doc
component_2
`-index.rst # component_2
component_3
`-index.rst # component_3
So far, I have tried a few workarounds, none of which is entirely satisfying:
Dummy root document
I tried creating a dummy root document containing:
.. toctree::
component_1
This approach has the following drawbacks:
The home page of my documentation is now the equivalent of a sitemap.
The existence of a dummy root document alters the navigation of the documentation (back/forward buttons and top breadcrumbs), so I can't really hide the home page away.
The sidebar structure is still not exactly the one I want:
Component 1
Subcomponents
Component 2
Subcomponents
Section A
Subsection a
Subsubsection i
Component 3
Subcomponents
Section A
Subsection a
Subsubsection i
Section A
Subsection a
Subsubsection i
I can improve things somewhat by running sed on the HTML output to replace all links to the root document (e.g. the link under the project icon) to links to Component 1 and erase the first level of the sidebar hierarchy, but the navigation issues remain.
Hidden toctrees
I tried using hidden toctrees to build the document hierarchy, and inserting the links manually to get the result I wanted.
The manual toctree technique is inspired from the Read The Docs manual itself.
The relative links masquerading as absolute ones is taken from the answer to another StackOverflow question, with a helping of sed to remove the #http:// anchors afterwards.
The root document ends up modified as follows:
Component 1
***********
Subcomponents
=============
.. toctree::
:hidden:
:caption: Subcomponents
component_2
component_3
:doc:`component_2`
:doc:`component_3`
Section A
=========
.. toctree::
:hidden:
:caption: Section A
Subsection a <#subsection-a#http://>
Subsubsection i <#subsubsection-i#http://>
Subsection a
^^^^^^^^^^^^
Subsubsection i
~~~~~~~~~~~~~~~
This approach has the following drawbacks:
I can't reuse the same template for the root document as for the other documents.
The document body looks identical, but as the underlying classes are all different, I'm one bad CSS update away from breaking my root document.
The sidebar structure is not the one I want, either. I can live with the top-level sections (actually the caption of the toctrees) not being clickable, but losing the indentation and the "you are here" highlighting is a dealbreaker:
Subcomponents (not clickable)
Component 2
Subcomponents
Section A
Subsection a
Subsubsection i
Component 3
Subcomponents
Section A
Subsection a
Subsubsection i
Section A (not clickable)
Subsection a
Subsubsection i (not indented)
My question, therefore, is: is there a better workaround to get the result I want, or should I take my chances with a feature request for Sphinx?
I have several documents that are independant from each others:
index.rst
foo.rst
bar.rst
conf.py
Makefile
I would like to access foo.rst from index.rst, but I would like the two subdocuments to start their numbering at 1.
In index.rst I have:
.. toctree::
:maxdepth: 2
:numbered:
foo
bar
But, bar will take the number 2. and with this bar.rst I will get 2.1 Tomatoes.
=====
Title
=====
Tomatoes
========
Cucumbers
=========
and I would like this rendering:
1. Tomatoes
2. Cucumbers
How is that possible?
You cannot have it both ways. See Sphinx documentation for Section numbering under the toctree directive for the explanation:
Section numbering
If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:
.. toctree::
:numbered:
foo
bar
Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the numbered flag to those).
Is it possible in some way to skip heading levels in RestructuredText? For example, given
####
PART
####
*******
Chapter
*******
Section
=======
Subsection
----------
Subsubsection
^^^^^^^^^^^^
Paragraph
"""""""""
Another section
===============
Another Paragraph
"""""""""""""""""
The above heading seems to be rendered as a subsection-level heading...
The last paragraph gets rendered as a subsection instead of as a paragraph. (I am using Sphinx as a renderer.) So it seems section-level detecting is local, although the RestructuredText documentation says it should be consistent:
All section title styles need not be used, nor need any specific
section title style be used. However, a document must be consistent in
its use of section titles: once a hierarchy of title styles is
established, sections must use that hierarchy.
When running Sphinx 1.3 on the document in the question, a warning is emitted:
C:\path\to\test.rst:24: SEVERE: Title level inconsistent:
"Another Paragraph" is on line 24 and it gets rendered as a subsection heading because that is what Sphinx expects at that position.
So no, you cannot skip heading levels. That is also how I interpret the meaning of the passage about consistency quoted in the question.
I am having an issue with getting the table of contents (TOC) to display subsections of the front page of my documentation.
I have a number of sections on my front page, and I would like these to be displayed in the TOC. The display of subsection works fine for every other page included in the TOC, but not self.
My index.rst code:
=====
Title
=====
Subsection
----------
Some documentation.
Contents
--------
.. toctree::
:maxdepth: 2
self
development
What I would expect to see in the TOC is this:
Title
Subsection
Contents
Development
Subsection
Instead what I get is this:
Title
Development
Subsection
I have found one solution so far, but it is not really satisfactory. I can put all the content in a separate page, then include the content in index.rst using an .. include: directive, and put the separate page in the TOC. This makes the TOC look right, but creates a duplicate page, which is now included in the navigation (previous/next page).
You could use the TOC directive from reStructuredText directly:
.. contents::
See http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
There are several issues with the section layout in the question:
Instead what I get is this:
Title
Development
Subsection
Using self as a toctree entry makes the outermost section title of the containing .rst file be included in that line of the toctree entry. The self entry will not render sub-sections or sibling sections, only the outermost section title. This goes against the usual properties of toctree entries.
Two resulting consequences of the above can immediately be noticed in the example from the question:
title and development are incorrectly rendered as being on the same level in the section hierarchy. When a .rst file is included in a toctree, its sections are placed below in the section hierarchy to the section the toctree directive is declared in.
title will be repeated twice, as being on different levels, if the containing .rst is placed in an exterior toctree.
Corresponding title.rst:
=====
Title
=====
Subsection
----------
Some documentation.
Contents
--------
.. toctree::
:maxdepth: 2
self
development
Corresponding development.rst:
development
===========
some text
Subsection inside development.rst
---------------------------------
Corresponding exterior.rst:
Exterior
========
.. toctree::
:maxdepth: 4
title
It's not a good design choice to aim for a section structure that works against the properties of the toctree directive. From the specification in the question, the simplest and conceptually soundest solution is to use the contents directive to list the sections within one given .rst document.
What I would expect to see in the TOC is this:
Title
Subsection
Contents
Development
Subsection
The easiest choice is using separate files title.rst and development.rst putting them in the same level in the index.rst toctree.
Corresponding index.rst:
Exterior
========
.. toctree::
title
development
To achieve tree of references both internal and external to a given .rst file the best solution is to use a simple bullet list of hyperlink targets.
Corresponding title.rst:
.. _target_title:
=====
Title
=====
.. _target_subsection_title:
Subsection inside title.rst
---------------------------
Some documentation.
.. _target_contents:
Contents
--------
text
- :ref:`Title <target_title>`
- :ref:`Subsection <target_subsection_title>`
- :ref:`Contents <target_contents>`
- :ref:`Development <target_development>`
- :ref:`Subsection <target_subsection_development>`
Corresponding development.rst:
.. _target_development:
development
===========
some text
.. _target_subsection_development:
Subsection inside development.rst
---------------------------------
Corresponding exterior.rst:
Exterior
========
.. toctree::
:maxdepth: 4
title
development
then include the content in index.rst using an .. include: directive
Use of the .. include:: directive would only change the place of the toctree problems without entirely solving them.