I am stuck on the depth of the toctree of my sidebar doc. Here's my doc : https://aff3ct.readthedocs.io/en/user_doc_dev/simulation/parameters/cdc/cdc_bch/cdc.html
As you can see, on the sidebar the toctree does not go deeper than the fourth level, but I have two other levels under. There is at the top of the page the Edit on GitHub link then you can see the source code.
I tried :maxdepth: -1 in any toctree directive but it changes only the display of the page's TOC and not of the sidebar's.
I tried on the first line of my first top file :tocdepth: 6, or with -1 or any big number, but it changes nothing.
I tried sphinxcontrib-fulltoc, but it never compiled; I did't find why.
Any idea ? Is it really possible to display deeper on the sidebar ? Is it a known bug ?
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'd like to add a simple warning directive at the top of every page on a Sphinx RTD site:
.. attention::
The next major release of this project will launch on X date.
In the meantime, we're looking for feedback.
If you'd like an early preview, please reach out at someemail#someaddress.com!
What's the simplest way to do this? I'm using the sphinx_rtd_theme.
I can see how to add a block using the extrabody block, but it appears outside the main content area and is positioned and styled totally independently.
Ideally, I'd want this block to show up at an attention directive just below the breadcrumbs on every page.
You could add this to the conf.py Sphinx configuration file:
rst_prolog = """.. attention::
The next major release is imminent.
"""
and it will be included at the beginning of every source file that is read ‒ see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog.
F-string literals work too, so f'This is release #{release}' will substitute that variable value.
I'm using the readthedocs theme for a personal sphinx documentation project. Everything works fine except the display of the left frame of the content list: It display all level of section headings, without showing any hierarchy. How to let it show levels as in most readthedocs documentation project?
After click the + sign, it looks right:
This is how I mark the section title:
Apache
======
How to restart
--------------
This sounds like this bug: Toc not expanding.
If not, please include your version of Sphinx, where you build the docs, and whether what you do to build the docs satisfies the conditions of that issue.
Otherwise, there is no configurable option to expand all options in the for the RTD Sphinx theme. See https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html#toc-options You will have to write custom JavaScript to make it so, and include the static asset with the theme. That homework is left to the questioner or a gracious answerer.
You could also file a feature request at https://github.com/rtfd/sphinx_rtd_theme/issues/new
This is the default behavior of sphinx. The section that you select expands on the left side bar. Else, it remains collapsed. https://docs.readthedocs.io/en/latest/versions.html this link also shows similar kind of behavior. To make it collapsible on clicking, you will require to update the theme.
I'm generating html documentation in Sphinx.
How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area instead of the sidebar.
Is there an easy way to do this? I'll be using readthedocs to host the generated documentation, so I would prefer to avoid the use of any third-party plugins, unless they are also available on readthedocs.
You can customize your html sidebar in conf.py.
The default html sidebar consists of 4 templates:
['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
In conf.py you could change localtoc.html to globaltoc.html like this:
html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
Since this in the end this will be used in HTML files, this should work on ReadTheDocs.
Including the 'globaltoc.html' has a drawback in that it doesn't show both the global and local toc for the page you're viewing.
It appears that others were irked about this limitation and resulted in the subsequent development of an extension to support a full toc in the sidebar, checkout: https://pypi.python.org/pypi/sphinxcontrib-fulltoc
Nothing will appear in the "Navigation" section of the default Sphinx sidebar until you add the names of files that you want to scan for section headings to the toctree:: directive in your .rst file.
For example, if you want all the headings of your index.rst file to appear in the Navigation pane, write index (without the extension) in the toctree:: list like so:
My Level 1 Heading
==================
Glorious content.
My Level 2 Heading
------------------
More content
.. toctree::
:maxdepth: 2
:caption: Contents:
index
The crucial bit is adding index right there at the end. If you're like me, you start your projects with the auto-generated template from sphinx-quickstart, which (at time of writing) populates your .rst files with EMPTY toctrees.