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.
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 couldn't find a directive that handles this.
Suppose to have a single rst document and for some reason you want to hide a single section during the build (no matter if HTML, PDF..), like:
Visible section
===============
Here some example I want to show
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
is there a .. hidden:: directive that handle this, I'm thinking of something like:
Visible section
================
Here some example I want to show
.. hidden::
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
.. visible::
Another section
===============
Other visible section in both text and final document
You can use comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments
The version of Sphinx I have got automatically generates an index.rst file that starts with a comment like this:
.. sphinx-quickstart on Sat Jun 22 15:48:19 2019.
You can adapt this file completely to your liking, etc
It does not show up in the documentation. You can start lines with two dots and a space followed by your own text and that does not show up either. You need to make sure that all the lines you create are indented the same as the first line. Then the whole section does not show up. Also make sure there is an empty line before the section and after it (unless it is the first section in the file or the last one)
Here is a solution to hide a section, so it doesn't show up in the HTML ouput.
However, this does not affect the build.
The idea is to use the class diretive and that way be able to assign a CSS class to the section(s). In CSS you can then define the class with display: none (or any other CSS).
For you example it would look like (note the identation):
Visible section
================
Here some example I want to show
.. class:: hidden
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
Another section
===============
Other visible section in both text and final document
In your css you add the following styling:
.hidden { display: none }
Here is a link that explains how to add custom CSS to Sphinx.
I have a Restructured Text document which several hierarchical sections, such as:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
This works great, I get the correct HTML formatting when I compile it using Sphinx.
My question is: how can I go up a hierarchy level so I can add more text after a few sub-sections?
For example:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
In my CSS, sub-section is indented.
I want this paragraph to be rendered as part of the Main title section,
not the sub-section.
I'm basically looking for a way to go up a level in the hierarchy.
Is this possible?
Thanks!
It's not possible to go "up" the hierarchy without starting a new section at the level you desire. Document section structure doesn't work that way. Changes in section level must be preceded by corresponding section titles. Using indentation to signal a section-like structure should only be used in a limited local scope.
What you're describing isn't a subsection, it's a topic. Docutils has a directive for that:
.. topic:: title
Topic text.
May include multiple body elements (paragraphs, lists, etc.).
There is also a "sidebar" directive for a similar structure, but typically for a parallel topic that's off to the side. The "rubric" directive may also be of interest.
See http://docutils.sourceforge.net/docs/ref/rst/directives.html for details.
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.