I have two duplicate keys -> .. command:: targetName in my doc on two separate pages. I need to know how can I link to these two separate targets using the following syntax:
Page-1 Click this -> :command:`targetName` # this will always open the first targetName declared in the doc
Goal:
Page-1 Click this -> :command:`targetName <page-1.html#targetName>` # not working :/
Page-2 Click this -> :command:`targetName <page-2.html#targetName>` # not working :/
Page-2 Click this -> `targetName <page-2.html#targetName>`_ # this will work but I don't want to use hyperlink instead of " :command: " cuz I want to keep my block style as is.
First some terminology. What you call targetName is called title in reStructuredText. The stuff in angle brackets is the target. See Cross-referencing syntax.
reStructuredText does not support nested inline markup, which includes styling hyperlinks. However there is a workaround with replacement.
As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use substitutions with the "replace" directive:
I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
In your case:
Page-1 Click this -> |myTarget|_
.. |myTarget| replace:: ``targetName``
.. _myTarget: page-1.html#targetName
For further customization of the appearance, use a custom style. See How do I set up custom styles for reStructuredText, Sphinx, ReadTheDocs, etc.? for one example.
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 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.
Following my other question Show/hide part of text (question/answer) in sphinx file what I would like to do is to export an html (or whatever format) without this tag (e.g. an html without all the admonition directives.
I read the .. only:: directive but it seems that you I can exclude an entire page from an html and let it in the latex for example.
You can nest directives by indenting them under one another.
.. only:: html
.. admonition:: Solution
:class: toggle
* Go to the dexterity-controlpanel (http://localhost:8080/Plone/##dexterity-types)
* Click on *Page* (http://127.0.0.1:8080/Plone/dexterity-types/Document)
* Select the tab *Behaviors* (http://127.0.0.1:8080/Plone/dexterity-types/Document/##behaviors)
* Check the box next to *Lead Image* and save.
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
Is there a way to add a tag to the format dropdown that would wrap the text in <small></small> tags?
Editing config.js as follows causes a runtime error:
config.format_tags = 'small;p;h1;h2;h3;pre';
probably because <small> is not block level?
The reason of the runtime error is, that js can not find CKEDITOR.config.format_small.
You have to do two things:
Search for CKEDITOR.config.format_h6 in ckeditor.js and add CKEDITOR.config.format_small={element:"small"};. Then the error is gone, but you can not see the entry yet.
open the languagefile you want (e.g. en.js) and add "tag_small":"small text".
now CKEditor supports the small tag.
This works for me, I hope it works for you too.
If I want to add a custom section tag to format tags, this work for me:
1. Go to config.js, add
config.format_tags = 'h1;h2;h3;h4;h5;h6;section';
config.format_section = { element : 'section' };
2. Then open the languagefile you want (e.g. en.js) -> lang/en.js
search for "tag_pre":"Formatted", and add "tag_section":"Section".
If you're looking to wrap text in a certain tag, you can also achieve this with the Style dropdown as well.
First, configure your editor to allow styles at /admin/config/content/formats/manage/full_html. Replace full_html with whatever editor version you want to modify
Drag the Styles button to the active toolbar if it isn't already there
Add items to "Styles Dropdown" tab under CKEditor plugin settings
Each option takes the form css_selector | Human Visible Name so in your case, you'd add small.my_element_class | Super Special Small or something similar.
Instructions abbreviated from this post: https://www.axelerant.com/resources/team-blog/drupal-8-custom-styles-in-ckeditor