I want to create a digital version of my lecture notes. I installed sphinx and changed the config.py file such that the ReadTheDocs theme is working.
I want to have a similar structure like in the following screenshot (from the Read the Docs Documentation)
My index.rst looks like
.. Lectures documentation master file, created by
sphinx-quickstart on Tue Jan 9 20:20:10 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
iLectures
======================================
Hello!
.. toctree::
:maxdepth: 2
:caption: Contents:
intro
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
How do I have to change the index.rst to have such a similar structure like in the screenshot? It would also be very nice if I could have an equivalent folder structure on my site as in the navigation? How can I refer to a file which is not in the same directory? I really appreciate any help.
tried indenting the new contents after the intro but it only led to an error.
The repository of Read the Docs has a docs directory which provides an example of how to render the navigation as you would like. The following is an explanation of what is going on.
The navigation screenshot is generated from two files, yaml-config.rst and index.rst. In the latter you will see that it references yaml-config.rst underneath a toctree directive.
.. toctree::
:maxdepth: 2
:caption: User Documentation
getting_started
versions
builds
features
support
faq
yaml-config
guides/index
api
embed
The index.rst file describes the file structure of the entire set of documentation, and represented in the navigation, to a maxdepth of 2. The yaml-config.rst file gets parsed by Sphinx and renders the navigation nodes under "Read the Docs YAML Config".
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.
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 have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
We are considering using Sphinx where I work and it appears to do everything we need. However, I am having issues getting it to match the required corporate template, which requires there to be some front matter pages inserted between the title page and table of contents.
If text is text is placed above the master table of contents in the .rst file, then it is placed above the TOC in the HTML output, but it is moved to below the TOC in the pdf output. I've also tried adding a hidden toc, but that didn't work either. The content also gets placed after the non-hidden toc.
.. toctree::
:hidden:
frontmatter
.. toctree::
:maxdepth: 2
contents_of_document
I know this has to be possible since people have published books using this tool, but I can't figure out how to do it.
I've tried this with sphinx 1.4.0 and 1.4.1. Is this something I need to add a latex sty or cls file to make it work? I would prefer not to since we would like to use both the HTML and PDF outputs.
Thanks
It looks like I need to RTFM. It is in chapter 10 to of the sphinx manual:
’tableofcontents’ “tableofcontents” call, default ’\tableofcontents’. Override if you want to generate a different table of contents or put content between the title page and the TOC.
So it order to do this, you need to learn some LaTeX as you will have to manually (or programmatically) write the from matter separately from the reST documentation.
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.