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.
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 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'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'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.