I'm writing documentation in RST format and generating HTML using Sphinx.
I want to be able to write a paragraph in an RST file and reuse the same paragraph in a different RST file in the same folder. I want the reuse such that if I make a change in the original paragraph it should automatically change in all other files it has been referenced when i generate the HTML using Sphinx.
Is there any RST syntax to make this happen? Any help is appreciated.
You can use the include directive.
For a basic include, reference the paragraph you want to reuse as follows:
Some text
.. include:: /path/to/file_to_include.rst
More text
In our example, the content of file_to_include.rst is Included text.
Sphinx will generate:
Some text
Included text
More text
As you can see in the docutils documentation (linked above), you can optionally specify a set of options, for example to restrict the included text to a range of lines.
Related
Context
I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).
Problem
I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.
Solutions (I have considered / tried)
toctree directive: Seems to only work with the sidebar, no matter what I try.
HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
Use the contents directive.
Here's the directive in its simplest form:
.. contents::
Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".
An explicit title may be specified:
.. contents:: Table of Contents
As #mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:
.. sectnum::
.. contents:: Table of Contents
:depth: 2
.. include:: intro.rst
.. include:: processes.rst
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.
In the RST Documentation file, after making a :ref command, I am unable to generate a link to the targetted section.
This is the edited file:
https://github.com/rahulchhabra07/pcl/blob/master/doc/tutorials/content/narf_keypoint_extraction.rst
This is the target file: https://github.com/rahulchhabra07/pcl/edit/master/doc/tutorials/content/range_image_visualization.rst
Kindly let me know, how do I make sure the link works for the label.
I think the issue is that the range image visualization file is not getting included in the project; it's not listed in index file. So when sphinx looks for the target label, it does not find it. If you don't want the target in the toc, you can include it in it's own toc and hide it:
.. toctree::
:hidden:
filename
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 using sphinx to generate the documentation of a python project and I'm making heavy use of external links. I'd like to build html and latexpdf outputs with these as clickable links (which is the default), but also a PDF version that will be printed, with these links showing up in footnotes.
In short: is there a way to write external links in a .rst file like this:
Ask a question on `my favorite Q&A website <http://stackoverflow.com/>`_.
and have a special output that will interpret this as if it was a footnote written like this:
Ask a question on my favorite Q&A website [#SO]_.
.. [#SO] http://stackoverflow.com/
while keeping the normal behavior (clickable link without a footnote) in other outputs?
Jongware's comment made me look at parts of the sphinx documentation I didn't see, and I realized there actually is a configuration variable that does what I want:
latex_show_urls = 'footnote'
As I wanted to be able to generate the usual pdf and the one with the footnotes without changing the conf.py file, I left the default value and added the following rule to the sphinx's Makefile:
.PHONY: printpdf
printpdf: SPHINXOPTS+=-Dlatex_show_urls=footnote
printpdf: latexpdf
This rule calls the regular latexpdf rule, adding -Dlatex_show_urls=footnote to the options given to sphinx-build.
With this, we can generate the PDF to be printed (with footnotes) with:
make printpdf
And if we want a regular PDF, without the potentially numerous and (here) useless footnotes, the regular rule still does it:
make latexpdf