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).
Related
I want to write a documentation page where I have something like:
Title
*****
Introductory text
Subsection with more details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Details
Section 1
=========
Section 2
=========
Unfortunately, this only renders Subsection with more details as the main section, with all subsequent ones being the subsections. From my research, it seems to happen because Sphinx doesn't have a fixed hierarchy for headings and instead it just interprets
the document structure to decide on what the sections are, based on their succession (as seen at https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
I have also tried using upper markup to titles, to force section hierarchy, but that doesn't seem to work either.
Is there a not too invasive way of doing this? This page is for an open source project with lot of documentation pages already, not all following the same markup standards, and I'm afraid that if I tried to somehow define in our settings what each section/subsection marker should look like, we would have a lot of formatting headache ahead of us... (or I would, hehe)
=========
Section 1
=========
Thanks in advance!
I need a way to escape from Sphinx’s limitation that HTML output contains one and only one page per level-1 heading. For the sake of readability, some of my document’s content must be divided into pages at a lower heading level.
I’m considering whether I can do this by manipulating the table of contents in the left sidebar, as follows.
Suppose I have a document with this structure:
Little section
A subsection
Another subsection
Big section
Level 2 in a big section
Another level 2 in a big section
Another little section
Normally the document would have three pages beginning with the headings “Little section,” “Big section,” and “Another little section.” But I want two additional pages, beginning with the headings “Level 2 in a big section” and “Level 2 in another big section.” I would do this as follows.
Put each level-2 section in a separate reST file, which makes its initial heading a level-1 heading from Sphinx’s point of view.
Add the :orphan: option to each “level 2” reST file so that it doesn’t appear in the sidebar TOC automatically.
Manually add level-2 entries to the sidebar TOC under “Big section” which have the text “Level 2 in a big section” and “Another level 2 in a big section,” and link to the orphaned “level 2” files.
I’m asking whether this is possible because I saw the following statement on sphinx-doc.org Directives page. I have put the relevant part in italics:
You can also give a “hidden” option to the [toctree] directive, like
this:
.. toctree::
:hidden:
doc_1
doc_2
This will still notify Sphinx of the document hierarchy, but not
insert links into the document at the location of the directive –
this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.
This appears to say: Yes, what I propose is possible. But I can’t find a clue to how it’s done. Can anyone provide insight?
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
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.