1,330 questions
1
vote
1
answer
100
views
Math expression in toctree entry fails to render using Furo theme
I am writing some Sphinx documentation with the Furo style. My index.rst file has:
.. toctree::
:maxdepth: 4
Bounds for :math:`|\zeta(s)|` <Art06.rst>
Size of :math:`L(1,\chi)` <...
- 131
0
votes
1
answer
103
views
How can I make sphinx latex builder add alt texts to sphinxincludegraphics?
I am tasked creating accessible documentation (PDF UA) from rst.
The idea was to use DocumentMetadata to enable tagging in general with something like a caption or :alt: to achieve this. However I ...
3
votes
1
answer
105
views
Clarification on reStructuredText directive indentation rules
I'm working with Sphinx to transform reStructuredText (rst) documents to HTML.
I've read documentation (primarily Sphinx's rST primer and Docutils rST documentation) and need clarification on the ...
- 6,455
3
votes
1
answer
90
views
Is there a way to generate superscripts from docstrings?
I have a GitHub Actions workflow setup with Sphinx and some extensions for document generation.
I was wondering if there is any way to set up a docstring such that Sphinx will generate in superscript, ...
- 305
1
vote
0
answers
64
views
How to mention parameters in a docstring [duplicate]
I am already familiar with :param name: description. I am asking a different question.
There are contexts in which I want to mention (as opposed to describe) a function/method parameter within a ...
- 498
1
vote
1
answer
84
views
How to add variable in versionadded admonition title
I have a variable defined in conf.py that holds the version and I use it everywhere else in my sphinx documentation with |version| with no issue. However it doesn't work for the versionadded ...
- 103
1
vote
1
answer
136
views
How can I enable word wrapping in inline code in a table?
The following table:
..
The 'widths' is an attempt to enlarge the first row. The behavior
stays the same without it.
.. list-table::
:widths: 75 10 15
:header-rows: 1
* - Init system
...
- 191
0
votes
0
answers
52
views
Sphinx: How do I protect individual table cells of an external CSV file from translation?
I use Sphinx (Python 3.13.3) and use the 'gettext' builder to create '.pot'/'.po' files.
Certain cells in a . csv-table:: should not be translated (e.g. registry keys, enum values), but they may occur ...
0
votes
0
answers
129
views
How to embed Plotly graphs into Sphinx tabs without losing it's interactive properties?
I'm making a sphinx web page to post work reports, mostly plotly HTML charts. I used .. raw:: html to add the graphs into my .rst file. Now, for better visualization purposes, I'm grouping my charts ...
- 49
1
vote
0
answers
48
views
Including two of the same reStructuredText (`.rst`) files in a Sphinx doc project
I am setting up a document structure such that I have everything in one main document, then using the .. only:: directive, but able to generate project specific versions by selectively choosing what ...
- 11
1
vote
1
answer
61
views
how to set the title of a table of content in rst sphinx
I have a simple table of content like that:
.. toctree::
self
doc/windows
doc/macos
doc/linux
I want to set the title of that table, but I can't find anywhere how to do it.
I have ...
- 403
0
votes
0
answers
62
views
Sphinx can't see function inside of my class when it builds
I have a project with this structure:
model_monitoring/
|-docs/
|-src/
| |-model_monitoring/
| |-class_name1/
| |-__init__.py
| |-class_name1.py
| |-class_name2/
| |-__init__.py
|...
0
votes
1
answer
51
views
How To Insert Image From File System Into RhodeCode Pull Request Comment
I would like to insert/embed an image from my local file system into a RhodeCode pull request comment (to aid in providing code feedback). RhodeCode uses a markup syntax/parser called reStructuredText ...
- 49
2
votes
2
answers
58
views
Docutils nested bullet lists termination
I have a problem with Sphinx/Docutils not recognizing the end of a nested list of bullet points. Code follows. It has been extracted from a much larger document:
.. rst-class:: level4 level
Editor
---...
- 2,937
0
votes
1
answer
80
views
How would I re-write labels and references to be unique using a Sphinx extension?
I am using Sphinx to generate documentation.
I have few (<10) folders with a lot of (>50) generated rST files that contain descriptions, but the labels and references are not unique between ...
3
votes
1
answer
266
views
Maintain image aspect ratio on scaled image with Sphinx/ReStructured Text
I have some documentation built with Sphinx, and I want my scaled images (figures) to behave the same as unscaled figures. For example, a figure declared as
.. figure:: images/manual_exposure1.png
...
- 853
1
vote
1
answer
113
views
Sphinx "only" directive with lists?
When using reStructuredText in Sphinx, how can I have optional list items using the only directive?
As an example:
foo bar:
- a
- b
.. only:: Internal
- c
- d
The problem with above is that it ...
- 782
0
votes
1
answer
196
views
How to reduce font size for a specific table in Sphinx with ReadTheDocs theme?
I am using Sphinx with the ReadTheDocs theme (sphinx_rtd_theme), and I need to reduce the font size of a specific table while keeping other tables unchanged.
I tried using:
.. list-table:: Issues &...
- 73
0
votes
1
answer
106
views
In RestructuredText how would you have automatic numbering of figures without a caption?
I put figures in a grid using sphinx-design and I would need multiple lines captions that have a specific layout, like certain items placed at the beginning of a new line.
I decided to place the ...
- 368
0
votes
1
answer
33
views
Sphinx generate documentation based on two separate sys.path
I have the following structure to be rendered as documentation
index.rst:
.. toctree::
:maxdepth: 2
:caption: Feature Family
feature/modules.rst
.. toctree::
:maxdepth: 2
:caption: ...
- 11
1
vote
2
answers
188
views
Sphinx: rST inline literal interpreted as code?
According to Docutils, double backticks around text is equivalent to the :literal: role: https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal
They show an example that these are equivalent:
...
- 61
0
votes
1
answer
215
views
Can the 'Unexpected indentation' error be suppressed with sphinx?
So I'm attempting to fix the warnings in an existing project, containing license.rst:
License
=======
.. include:: ../LICENSE.txt
where LICENSE.txt has this structure:
Copyright ...
... provided ...
- 682
0
votes
0
answers
54
views
Combine :target: and :download: in sphinx-doc
If I have this tree file in sphinx-doc project directory
_build
index.rst
...
foo.rst
foo/myimage.jpeg
foo/myvideo.webm
I want to display in foo.rst image foo/myimage.jpeg which links to foo/myvideo....
- 1,617
0
votes
0
answers
86
views
Syntax for Multiple Index Entries in Sphinx
I would like to know if there is a way to add multiple index entries in Sphinx.
In the tutorials, I've found that only two entries can be added using the format
.. index:: main_entry; sub_entry
...
- 1
0
votes
1
answer
153
views
Sphinx docs & ReStructured Text: Substitution on parameter definition on multiple lines
I am developing a project in Python that has hundreds of functions. A lot of them have a parameter called verbosity, which I describe the following way:
"""
verbosity: int, optional
...
- 296
0
votes
1
answer
87
views
How to use letters for restructured text lists with more than 26 items?
If I make a Restructured Text list with letters as the bullets, this works fine for the first 26 letters "a.".."z.". However, when I extend the list to 27 items or more, such as ...
- 729
1
vote
1
answer
143
views
How to prevent sphinx replacing upper-case letters with lower-case in the target of a cross-reference?
This came to be, because I am currently changing our old documentation to a new one using sphinx. The old documentation used t2t files in which I have a lot of references written with capital letters ...
- 55
0
votes
1
answer
79
views
reStructuredText: Fix section/headline level when including file
I have a couple of dozen .rst files that are all loaded from a main index.rst file via .. include: file.rst.
Now I want to restructure the TOC and move some files onto a different headline level - but ...
- 31.4k
0
votes
2
answers
61
views
Add CSS class to Sphinx-generated anchor span
With this RST file:
.. cssclass:: myclass
.. _important:
Something really important
--------------------------
...and this call:
sphinx-build -C ./ ./html ./index.rst
...the following HTML results:
...
- 18.1k
4
votes
2
answers
357
views
How to write multipe math equations inline on a single line in Sphinx
I want to write a simple line as below in my Sphinx reST document:
To write the line using :math: flag:
We know that :math:`A \to B \vdash A \to \forall x B`, provided that :math:`x` is not free in :...
- 435
-1
votes
1
answer
76
views
In Visual Studio Code, how can I rename a variable in Python and also update its occurrences in ReST formatted documentation?
Suppose I have:
class Hello:
"""An example class."""
world: str
"""This is the only field on :py:class:`Hello`."""
It is documented ...
- 4,684
0
votes
0
answers
58
views
Linking a Sphinx/RST project to external spreadsheet/database
I'm creating an operations manual for a restaurant using Sphinx and RST, that has entries for various recipes. The recipes are currently in a Google sheet, that is mostly maintained by other people.
I ...
- 79
1
vote
1
answer
1k
views
Theme error: no theme named 'furo' found (missing theme.conf?)
I would like to preface that I am a complete beginner to Sphinx documentation.
That being said, I have had immense difficulties trying to troubleshoot this issue.
I am trying to use the "furo&...
0
votes
1
answer
96
views
When using Sphinx for rst file, how to make replacement defined in rst_prolog effective in lines which are quoted by " ` "？
I‘ve defined a replacement in conf.py:
rst_prolog = """
.. |tools| replace:: Something
"""
Below is the rst file, the replacement is effective in line 1, but doesn't ...
0
votes
1
answer
89
views
Sphinx doc toctree click "jumps" to nav anchor instead of top
When I click a toctree (navbar) item, the page "jumps/jolts" to the toc element instead of the top of the new page as if it's aligning with the toctree anchor (instead of the body h1 or just ...
- 1,063
2
votes
1
answer
73
views
MathJax rendering issue in Sphinx with ␣ symbol
I am building documentation using Sphinx. I have the following in a rst file:
.. math::
{{a^{{p_1}{p_2}}_{{p_3}{p_4}}}{a^{␣\,{p_5}}_{{p_6}{p_7}}}}
While building, this produces "Math input ...
- 67
1
vote
2
answers
293
views
Add additional class to Interpreted Text Roles in Sphinx
What I am trying to achieve is to (manually) insert a html-class to certain elements using sphinx' python domain
For example I have this string:
Lore Ipsum :py:mod:`dataclasses`
Which results in:
...
- 5,245
-2
votes
1
answer
144
views
Sphinx RTD Theme improperly nesting subheadings
I have a single index.rst file that has the contents of my README.rst included using the .. include:: directive. When rendering this using make latexpdf or using the .. contents:: directive in html, ...
0
votes
1
answer
114
views
How format doc within :param <name>: in reStructuredText markup?
I am trying to document certain :param and want to give examples like
:param mapper_matrix:
lookup table with columns ref_col, ref_col_2 and value.\n
|**Example:**
| ...
- 13.1k
0
votes
1
answer
187
views
How to style a specific container in rst2pdf
I have the following restructuredText for a page header, for which I want a logo image on the left and a document title aligned right:
.. header::
.. container:: twocol
.. container:: ...
- 8,163
0
votes
1
answer
300
views
docutils traverse sections and create list of subsections with their paths
This questions attempts to extend the code from Jason S (Thanks, Jason), found here: Docutils: traverse sections?.
Original from Jason S
import docutils
def doctree_resolved(app, doctree, docname):
...
- 51
0
votes
1
answer
120
views
In rst file, how can I provide a link to file with %APPDATA% so it is independant of user?
I have link in a rst file that refers to a local file, which will be in a path dependant on user name, such as:
`The link to my file <file:///C:\\Users\\USERNAME\\AppData\\Local\\Apps\\myfile.html&...
- 345
0
votes
1
answer
1k
views
Adding tabs restructured text (rst) files
How can I tabulate information in my rst files?
Or, how do I preserve the white space I already inserted in my text?
Such that when I render the rst file (via Sphinx) to HTML the tabular formatting is ...
- 1
0
votes
1
answer
155
views
reference sphinx |version| as monospace and no leading spaces
I'm trying to reference the sphinx |version| in a monospace block (and no spaces around it) in my .rst file like this...
You can install foo_project library with:
``pip install -U foo_project==|...
- 43.3k
0
votes
1
answer
63
views
Why won't Sphinx include my Ruby code examples?
I've got a .rst that has both Ruby and Python coding examples in it, but I am now in the position where I need to dyanimcally change the examples, so I'm setting the code example to an external file (...
- 958
0
votes
1
answer
188
views
Sphinx is throwing some indentation errors, and I cannot figure out how to fix them
These are the errors I am getting from Sphinx:
Unexpected indentation:
[{
"resource": "/c:/Users/User/Documents/GitHub/MIMIC/mimic/model_simulate/base_model.py",
"owner":...
0
votes
1
answer
84
views
RST Sphinx custom extension for xml
I am trying to understand how to create a custom Sphinx extension which can be executed only when creating XML. I would like to put a custom RST directive
.. mycustom::
and output a consequent XML ...
- 41
0
votes
0
answers
73
views
How to get blockdiag directives rendered to HTML?
I'm trying to add programmatically-rendered diagrams to my reStructuredText documentation, which I render to HTML with Sphinx.
Per https://lpn-doc-sphinx-primer-devel.readthedocs.io/extensions/...
- 6,455
0
votes
1
answer
96
views
Sphinx warning: Failed to import test.test_adder from module `pythontemplate`
Context
After creating a root_dir/docs/source/conf.py that automatically generates the .rst files for each .py file in the root_dir/src (and root_dir/test/) directory (and its children), I am ...
- 2,931
1
vote
1
answer
76
views
After creating a subsection, how to make a paragraph part of the parent section?
The following is a block of reStructuredText that defines a "Main Section" and two subsections, each with a sentence of content.
Main Section
============
This is some main section content.
...
- 6,455