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.
Related
I have a .. toctree as part of a sphinx page, which includes relative links to other rst files in my package. How can I include a link to a subsection of a given page, rather than the full page itself?
I took a stab at
.. toctree::
page#section
But that didn't work. Any help is great.
After much hackery, I've come to the following solution, but I should first state that my goal was to:
have the heading NOT appear in the content body
have the heading appear in the TOC
So basically linking from the TOC to an arbitrary but invisible part of a document.
I needed this in order to be able to link to methods in some source code documentation rendered with Sphinxcontrib PHPDomain - these methods generate section links of their own, but do not get added into the TOC by default.
Step 1:
At the top of your RST file which needs this linking functionality, add a new role as such:
.. role:: hidden
:class: hidden
Step 2:
Somewhere in the content, use this role as such:
:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""
Step 3:
Add new CSS to the project (usually done by adding a CSS file into _static, or defining a style sheet or something like that - see this):
.rst-content .hidden {
display: none;
}
nav .hidden {
display: unset;
}
This forces the heading to be hidden in the content, but shown in the TOC.
Then, reuse the role as necessary in other documents.
Note that if your goal is to link to arbitrary locations in the document and still have the headings show up in the content, just change the CSS to style the headings to your liking rather than hide them.
When creating the ToC, Sphinx is including all headings and subheadings of referenced files within the configured tree depth. So you can simply not start the page with a heading and insert the heading at the point you want the ToC to point to, e.g.:
.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive
And here some more text, normal font weight.
Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...
You need to include the page reference in the ToC as usual.
So in the ToC, you have:
.. toctree::
my_rst_file
In our example, the build result (HTML, PDF, whatever) will only have a reference to Here comes the heading that will appear in the ToCin the ToC.
Using Sphinx documentation generator (with pdflatex), I am creating pdf files and have added links to some of the internal files using label and ref markups like this:
In the called file (xyz.rst)
.. _called-file-label:
In the calling file(abc.rst) I am adding a reference to the label like this:
:ref:`Get Info <called-file-label>`
With the above arrangement, I am able to generate pdf file using pdflatex. However, I find that the called file is also added to the pdf file's bookmarks section which feels somewhat clumsy.
I understand I need to add both the source files in the .. toctree:: section for the hyperlink to appear in the pdf file (I have added the called file using :hidden: directive to prevent the file from showing up in the html document's ToC tree).
My question is: What do I need to do in order that the called file (xyz.rst) does not figure in the bookmarks section of the generated pdf file?
If after .. _called-file-label: label is section:
.. _called-file-label:
Foo Bar
======
Then, the section title "Foo Bar" will always become a bookmark in PDF.
The :hidden: option of toctree is not to hide documents, but to don't show ToC on the place with toctree. I.e. it is to hide toctree, not its documents. Documents in hidden toctree will still be visible in HTML sidebars, PDF bookmarks, etc.
It looks like you need rubric directive. Rubric is like a section, but doesn't make up the table of contents.
I'm using the sphinx documentation system to generate reports in both HTML and Latex output formats. So have a hierarchical structure where I have a read index.rst which contains a toctree that references all chapters in order of appearance. Then a chapter is a folder which also contains an index.rst with only a header and a toctree which includes all sections for that chapter.
So as an example my structure looks likes this:
root
- index.rst <- Contains only a toctree that references other chapters index.rst.
- SomeChapter
- index.rst <- Contains heading and toctree that references actual content
- section1.rst <- actual content
- section2.rst <- actual content
....
This renders beautifully with latex since you will literally get someChapter and below that the sections but in html those are all seperate pages which get's boring quick for some smaller subsections since you have to keep clicking around. Is there a way to instruct the html builder that in some cases it should show the subpages in the same page where they are in the toctree and not create subpages for it?
I know about singlehtml but that does build an entire single html page for it and I want to do it partially because a lot of times different chapters are great with different pages but sections can be easily on the same page.
Any help is appreciated.
Untested answer.
Have two different index pages, one for HTML (index.rst) and LaTeX (indexlatex.rst), where the latter is a copy of the former, then the former gets modified.
Then in your conf.py, specify indexlatex.rst as the entry toctree. Example from Pyramid:
latex_documents = [
('latexindex', 'pyramid.tex',
...
)
Finally to modify index.rst, you would use a series of include directives and remove the toctree directive.
.. include:: section1.rst
.. include:: section2.rst
You might also need to use :orphan: metadata on the latexindex file to suppress warnings about it not being included in the index's toctree.
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
I have a .. toctree as part of a sphinx page, which includes relative links to other rst files in my package. How can I include a link to a subsection of a given page, rather than the full page itself?
I took a stab at
.. toctree::
page#section
But that didn't work. Any help is great.
After much hackery, I've come to the following solution, but I should first state that my goal was to:
have the heading NOT appear in the content body
have the heading appear in the TOC
So basically linking from the TOC to an arbitrary but invisible part of a document.
I needed this in order to be able to link to methods in some source code documentation rendered with Sphinxcontrib PHPDomain - these methods generate section links of their own, but do not get added into the TOC by default.
Step 1:
At the top of your RST file which needs this linking functionality, add a new role as such:
.. role:: hidden
:class: hidden
Step 2:
Somewhere in the content, use this role as such:
:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""
Step 3:
Add new CSS to the project (usually done by adding a CSS file into _static, or defining a style sheet or something like that - see this):
.rst-content .hidden {
display: none;
}
nav .hidden {
display: unset;
}
This forces the heading to be hidden in the content, but shown in the TOC.
Then, reuse the role as necessary in other documents.
Note that if your goal is to link to arbitrary locations in the document and still have the headings show up in the content, just change the CSS to style the headings to your liking rather than hide them.
When creating the ToC, Sphinx is including all headings and subheadings of referenced files within the configured tree depth. So you can simply not start the page with a heading and insert the heading at the point you want the ToC to point to, e.g.:
.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive
And here some more text, normal font weight.
Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...
You need to include the page reference in the ToC as usual.
So in the ToC, you have:
.. toctree::
my_rst_file
In our example, the build result (HTML, PDF, whatever) will only have a reference to Here comes the heading that will appear in the ToCin the ToC.