I have Sphinx documentation containing math blocks via the math directive. By default, they are centered in the HTML output. I want them all to appear aligned at the left, but with some indentation with respect to the surrounding text.
For example, if this is in index.rst
For :math:`|r| < 1`:
.. math::
\sum\limits_{k=0}^{\infty} r^k = \frac{1}{1-r}
Text in following paragraph put here to demonstrate that the math block
is in fact centered on the page.
and conf.py is completely empty, then running sphinx-build . output in the same folder produces the following HTML page as viewed in the browser:
I want that formula and all other math blocks left-aligned with something like 2 "em" indentation. This question asks how to left-align a single math block. I'm hoping there is a way to achieve the same effect throughout the documentation without changing each and every math directive in the reStructuredText source.
This answer applies to MathJax, the default mathematics renderer in HTML output.
The following setting in conf.py left-aligns all math directive content:
mathjax3_config = {'chtml': {'displayAlign': 'left'}}
Indentation can be customized with displayIndent:
mathjax3_config = {'chtml': {'displayAlign': 'left',
'displayIndent': '2em'}}
References:
https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config
https://docs.mathjax.org/en/v3.0-latest/options/output/index.html#options-common-to-all-output-processors
Related
I'm new to MyST and Sphinx, so perhaps this has an obvious explanation, but it is not obvious to me. Whenever I use any construct in my Markdown source, such as bold facing or italics or even an html element such as <span>, the result in the formatted HTML output contains spaces inside the HTML tags. For example, an input such as
* **Barcode**: the barcode identifying the item
* **Title**: the title of the item.
* **Author**: the author of the item.
produces this:
Note the space before the :. Inspecting the HTML reveals that the bold-faced element contains unexpected space characters:
Note the spaces inside the <strong>...</strong>. Why is this happening? What am I doing wrong? More importantly, how do I make it stop?
I'm using Sphinx 3.4.3 with myst-parser 0.13.3. My conf.py defines extensions as 'myst_parser', 'sphinx.ext.autodoc', 'sphinx.ext.autosectionlabel', and 'sphinx.ext.napoleon'.
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.
In every renderer I've tried, code and code-block seem to have the exact same result: a block of code. Both generate the exact same html -- including classes and tag kind (using I think it was docutils?):
<pre class="code [language] literal-block">
So, what's the difference? Why do we have both? Are there any renderers that render them differently? Is there a semantic difference?
code is a reStructuredText directive.
code-block is a Sphinx directive.
The code-block has a different set of options to the codedirective.
E.g. :emphasize-lines:
As you are using Sphinx I would recommend using the code-block directive.
When using code-block I always get the correct highlighting. When using code I sometimes get colors and sometimes just literal code blocks. I have yet to figure out what combinations of setting in conf.py that predictably generates colored output.
The code directive does have the advantage that the document can be used both in a Sphinx document tree and at the same time as a stand-alone reStructuredText document.
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
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.