I'm trying to create a single entry on the main toctree with three nested entries that each link to a page (because our main TOC is already quite long). The structure is like this:
- Layers
+ Using Layers
+ Layer Arguments
+ Layers List
Layers is layers.rst and Using Layers is a heading in layers.rst. I created two more headings in layers.rst for Layer Arguments and Layers List because I want them to be on the same level. I created a toctree under the Layers Arguments heading, and a second one under Layers List so when you click on them it brings you to the TOC under each heading.
When you click Layer Arguments/Layers List I want it to go to the top of layer_args.rst/layers_list.rst, not to the heading in layers.rst. Is it possible to create a nested toctree that links to files in the sidebar?
Edit: Example
index.rst
<some headings and text>
.. toctree::
:maxdepth: 2
:caption: Layers
layers
layers.rst
.. _using-layers:
------------------------------------------------
Using Layers
------------------------------------------------
<text>
------------------------------------------------
Layer Arguments
------------------------------------------------
.. toctree::
:maxdepth: 2
Layer Arguments <layers/layer_args>
------------------------------------------------
Layers List
------------------------------------------------
.. toctree::
:maxdepth: 2
I/O Layers <layers/io_layers>
Operator Layers <layers/operator_layers>
Transform Layers <layers/transform_layers>
.
.
.
layers/io_layers.rst
layers/operator_layers.rst
layers/transform_layers.rst
I would move the file layers.rst to layers/index.rst, and adjust paths accordingly. Thus your directory structure and navigation structure align with one another.
docs/index.rst
.. toctree::
:maxdepth: 2
:caption: LBANN Layers
layers/index
docs/layers/index.rst
------------------------------------------------
Layer Arguments
------------------------------------------------
.. toctree::
:maxdepth: 2
Layer Arguments <layer_args>
------------------------------------------------
LBANN Layers List
------------------------------------------------
.. toctree::
:maxdepth: 2
I/O Layers <io_layers>
Operator Layers <operator_layers>
Transform Layers <transform_layers>
Related
Suppose I have:
a foo0.rst file at the root (source) of my sphinx-doc source folder,
a foo1.rst file in a subfolder subfolder1 of source,
a foo2.rst file in a subfolder subfolder2 of subfolder1,
that is:
$ tree source
source
├── foo0.rst
└── subfolder1
├── foo1.rst
└── subfolder2
└── foo2.rst
all with the same content:
This a title
============
Now, if the index.rst contains:
Welcome to Test's documentation!
================================
.. toctree::
:maxdepth: 3
:caption: Contents:
foo0
subfolder1/foo1
subfolder1/subfolder2/foo2
make html gives:
Welcome to Test’s documentation!
Contents:
• This a title
• This a title
• This a title
that is all the headings are sections.
What I would like to get instead is the following:
Welcome to Test’s documentation!
Contents:
• This a title
◦ This a title
▪ This a title
that is the heading of:
foo0.rst being a section,
subfolder1/foo1.rst being a subsection (and not a section),
subfolder1/subfolder2/foo2.rst being a subsubsection (and not
a section).
My question is therefore: is it possible to make the heading levels of
documents belonging to (sub(sub(...)))folders automatically depend on
the depth's levels of the folders they belong to?
The style applied to the toctree entries is dependent on the theme you are using. The theme's CSS will apply a style to the entries that Sphinx translated into <ul> and <li> depending both on their place within the "document hierarchy" given how you chain the toctrees and how your section structure in the individual .rst files is organized.
For example, inspect the HTML elements Sphinx generates. The toctree will be a div class="toctree-wrapper compound" with each level of sections being named <li class="toctree-l1"> then <li class="toctree-l2">, etc...
One way to achieve what you want would be to surround a given toctree using a .. class:: directive (as show here) and apply a custom style. But that would then impact the style of any other .rst files you want to include as entries in that toctree.
In any case, you will incur in extra work and potentially loose automatism if you refactor your project.
There is also one possible workaround, using the :hidden: option together with the :include: directive. If you declare a hidden toctree before a visible toctree the "document hierarchy" can fix the position of an entry for you in the hierarchy. Afterwards the visible toctree without the :hidden: option will render .rst file entries as a <li> element having a fixed position in the hierarchy. (A thorough example can be seen in this post).
It can be done, but you will be working against the characteristics of the toctree.
The prevalent solution is writing your .rst files and sections depending on how you want the toctree to display. (This approach has all the advantages with the only drawback of putting restrictions on how you write the .rst files). It's probably the preferable solution rather than trying to adapt the CSS styles or using workarounds.
EDIT:
What I wrote before is valid, but probably too general. So I'll give one possible solution to the example. If you want the following:
Contents:
• This a title (foo0)
◦ This a title (foo1)
▪ This a title (foo2)
A simple option is using a chain of toctrees. You can hide the toctree's that are lower in the document hierarchy if you don't want to see them.
index.rst
.. toctree::
:maxdepth: 3
foo0
and in foo0.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/foo1
and in subfolder1/foo1.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/subfolder2/foo2
The result will be as you specified.
Lets say I have two .rst files, a welcome page (the index) and an API page. I would like them both to have identical toctrees, so it is easy to navigate from the one page to the other.
index.rst:
Welcome!
========
Welcome to these awesome docs!
api.rst:
API
===
Here is some API stuff...
I tried adding a toctree to index.rst, something like this:
.. toctree::
:hidden:
index
api
However then my toctree gets nested:
I do not only want to add
.. toctree::
:hidden:
api
to index.rst and
.. toctree::
:hidden:
index
to api.rst, since that means that the sidebar is different between pages.
How do I add a global index to my project? One that is the same no matter which page I am on?
I'm trying to learn how I can manage a toctree element that is located in the same file as other content.
Suppose I have a thingamajig.rst chapter that looks like this:
Thingamajigs
============
.. toctree::
:maxdepth: 2
foo
bar
baz
Overview
++++++++
Thingamajigs are fun
When I render it --- foo/bar/baz have their own .rst files --- it looks like this:
But if I move the Overview section before the toctree, then it pushes the toctree down into the Overview section:
Thingamajigs
============
Overview
++++++++
Thingamajigs are fun
.. toctree::
:maxdepth: 2
foo
bar
baz
Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?
Alternatively, can I do something like this?
Thingamajigs
============
.. toctree::
:maxdepth: 2
Overview <-- refers to Overview section in same file
foo
bar
baz
Overview
++++++++
Thingamajigs are fun
The exact specification given in the question can be satisfied, but not without significant issues that require workarounds.
Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?
By placing a toctree inside the Overview section your are placing all of that toctree's "Entries" (.rst files) inside that section and thus below that level in the section hierarchy.
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.
Pacing a toctree outside its pretended section will impact 1) "navigation", 2) "numbering" and 3) "depth".
First step of the workaround:
You can declare a toctree with the :hidden: option exactly where you want it -inside the Thingamajigs section- thus having 1), 2) and 3) working as intended. Sphinx will process the entries in the first toctree declaration, so afterwards the toctree declared inside Overview won't affect 1), 2) and 3) because the .rst entries were already processed.
The result:
Corresponding thingamajigs.rst:
Thingamajigs
============
.. toctree::
:hidden:
foo
bar
baz
Overview
++++++++
Thingamajigs are fun
.. toctree::
foo
bar
baz
The above satisfies the problem exactly as it was specified in the question.
(Sphinx will issue warnings because the same .rst file was included in more than one toctree, but they aren't errors just warnings.)
Second step of the workaround:
However, now comes a surprise! If you go one level up, to the .rst containing the toctree that has thingamajigs.rst as an entry, you'll find the :hidden: toctree wasn't rendered, and instead the visible toctree is rendered "in place" (out of order):
The result:
Corresponding level_2_toctree.rst:
***************
Level_2_toctree
***************
.. toctree::
fill_tree1
fill_tree2
fill_tree3
fill_tree4
thingamajigs
Although 1), 2) and 3) are working (in terms of the toctrees retaining their functionality), this leaves us with a problem: fixing the rendering order in parent toctrees. The obvious solution is to repeat the original lower level toctree "as is" inside a bullet list and adding references targeting the sections:
The result:
Corresponding level_2_toctree.rst:
***************
Level_2_toctree
***************
.. toctree::
fill_tree1
fill_tree2
fill_tree3
fill_tree4
.. toctree::
:hidden:
thingamajigs
- :ref:`5.5. Thingamajigs <target_thingamajigs>`
.. toctree::
foo
bar
baz
- :ref:`5.5.4. Item Overview <target>`
.. toctree::
foo2
bar2
Notice you would have to add hyperlink targets to the original thingamajigs.rst.
.. _target_thingamajigs:
Thingamajigs
============
.. toctree::
:hidden:
foo
bar
baz
.. _target:
Overview
++++++++
Thingamajigs are fun
.. toctree::
foo
bar
baz
Third step of the workaround:
But this has another problem, the HTML theme may have different CSS styles for bullet lists and toctrees, both are processed as different HTML elements (examine the source).
One solution would be to wrap the block including the 2 delimiting references in a reST directive (a container) that allows for custom styling as to make the block "blend in" with the remaining toctree. However, you would have to propagate this customizing at every step of ascending the toctree chain.
This does provide a general solution as "proof of concept" for having a "portable toctree" placed out of context. The two main drawbacks are having to manually refactor the hyperlink numbering, and the overhead and expertise required to customizing the CSS.
No more workarounds:
Consider the Sphinx toctree directive and the reStructuredText contents directive are very different. While the whole point of the toctree is chaining .rst files together, the aim of the contents directive is providing a nice table of contents of the .rst file (or the section) it is in.
Try the useful :backlinks: option of the contents directive, by clicking back and forth between the upper index and the corresponding section of its documentation.
"Ideally" the best way to avoid workarounds is using the right tool for the job at hand.
The third option that's a complement to the above two is using a bullet list made of hyperlink targets. It's flexible and allows to mix links both internal and external to the .rst file containing the bullet list. Plus it doesn't interfere with the automatisms of the toctree or the contents directives - which depend on sections. The second step of the workaround includes both of the bullet lists' essential elements.
I'm trying to learn how I can manage a toctree element that is located in the same file as other content.
Looking at toctrees in the official Python documentation one example, or another example you see the "Flat, Simple, Special cases..." from the Zen of Python reflected. Most prominent documentations I've seen chose simple toctree layouts.
Without changing the specified presentation, the most efficient solution is using a bullet list of references to hyperlink targets inside Overview instead of the toctree.
The section headings hierarchy is simply the order as encountered. So your ==== underline sets the title ("H1") and ++++ underline sets the subtitle ("H2") for this page only. Depending what layout you're after...
A. Maybe you wanted a "Table of contents" section as a sibling of the "Overview" section (both within "Thingamajigs" parent), so insert a new H2 section heading:
Thingamajigs
============
Overview
++++++++
Thingamajigs are fun
Table of contents
+++++++++++++++++
.. toctree::
:maxdepth: 2
foo
bar
baz
B. Or maybe you don't want "Overview" in the section headings hierarchy at all, so highlight it by a different means:
Thingamajigs
============
.. admonition:: Overview
Thingamajigs are fun
.. toctree::
:maxdepth: 2
foo
bar
baz
C. Or list the headings hierarchy within this page, separately from external pages:
.. contents:: In this page
:local:
.. beware, that contents directive must appear before any heading hierarchy
Thingamajigs
============
.. toctree::
:maxdepth: 2
:caption: In other pages
foo
bar
baz
D. Or do exactly what your last example showed: move the "Overview" content out to a separate ReST document and include its name in the toctree directive body.
Others have commented about toctree and contents, so I won't repeat them.
You can do a hack with the raw directive.
Thingamajigs
============
.. raw:: html
<h2><span class="section-number">1.1. </span>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
.. Overview
.. ++++++++
Thingamajigs are fun
.. toctree::
:maxdepth: 2
foo
bar
baz
To get the HTML that I used in the raw directive, I started with "Overview" and its underline to generate the HTML. Next I copied it from the generated HTML and pasted it as you see above, indenting it under the raw directive. Finally I commented out "Overview" and its underline. You can season your raw HTML to taste.
Personally, however, I do not see the point of having both a title, immediately followed by an "Overview" or "Introduction" heading, immediately followed by the content of the overview or introduction. I would remove the heading and simply display the desired content. It's obvious what it is, so why does it need a heading?
My issue is hard to convey with words. I'll try the best I can.
Using Sphinx 2.0.0, I have a project with the following "root" toctree. This is the index toctree:
Welcome to FIRST Robotics Documentation
========================================================
.. toctree::
:maxdepth: 2
:caption: WPILib Software
software
.. toctree::
:maxdepth: 2
:caption: WPILib Hardware
hardware
.. toctree::
:maxdepth: 2
:caption: Robot Networking
networking
This works great.
I now have a structure that looks a bit like this:
Now let's use the "software" toctree index page
.. toctree::
:maxdepth: 1
quick urls here
Getting Started
===============
.. toctree::
:maxdepth: 1
docs here
WPILib Overview
===============
.. toctree::
:maxdepth: 1
docs here
This gives me a page that looks like this:
However, the issue is when you begin to navigate into the sub-sub-toctrees. When you go into the "WPILib Overview" section, the top nav-bar shows as "Getting Started", this is reproducible throughout the other sections as well.
In the above image, it should show "WPILib Overview" instead of "Getting Started". Unfortunately it does not.
Source code is available publicly at: https://github.com/daltz333/frc-docs
Webpage source and problem URL at: https://frc-docs.rtfd.io/en/develop
I can't think of any solution besides breaking every single section into it's own file, which is not an option.
You need to set the navigation_depth as a property of html_theme_options in conf.py, i.e.:
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'navigation_depth': 2
}
For more information see their documentation on configuration of theme options.
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.