3,847 questions
Advice
0
votes
2
replies
35
views
Have sphinx avoid naming `index.html` unnecessarily in its links?
Our project's sphinx-generated HTML includes many links to index.html files (e.g., path/to/index.html) rather than linking to the directories themselves (e.g., path/to/). Is there an option or best ...
- 4,174
3
votes
1
answer
76
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,435
2
votes
2
answers
59
views
myst_parser WARNING: 'myst' cross-reference target not found
When I compile my docs with Sphinx and a Markdown file, using myst_parser, I get a warning for cross-reference not found, even if after compilation links works well.
test_page.md:
# test page
[click ...
- 341
0
votes
0
answers
72
views
How to correct 3rd party sphinx ambiguous cross-reference warnings?
I'm trying to document a variety of classes that use scikit-learn bases BaseEstimator and TransformerMixin. Sphinx builds with a warning that,
/home/jake/github/proj/pkg/__init__.py:docstring of
...
- 1,806
1
vote
0
answers
41
views
Using Sphinx autosummary to generate documentation for class instances stored as attributes during instantiation of another class
I have a class called WebAPI that instantiates and stores a UserEndpoints object inside its constructor:
# /src/minim/api/spotify/_core.py
... # other imports
from .._shared import OAuth2API
from ....
- 528
1
vote
0
answers
55
views
How should I install CUDA dependencies in readthedocs build with apidoc autodoc
I have a python project which uses readthedocs and its apidoc/autodoc to build API documents automatically. The project uses a third-party tool that can only be installed from source like this: pip ...
- 2,337
1
vote
2
answers
71
views
Sphinx getting a <ul> with a class
I am quite new to Sphinx.
My code:
.. _ahn-kwon-14:
* A----. 2014, J. Number Theory, 145, 433--473.
It gets translated into
<ul class="simple" id="ahn-kwon-14">
<li>&...
- 111
1
vote
1
answer
93
views
How to update the table of contents (toctree) in a Sphinx extension?
I am writing a sphinx extension where I want to filter sections dependent on parameters provided to the sphinx-build.
In the first approach I just removed certain sections that where somehow ...
- 41
3
votes
1
answer
76
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, ...
- 195
1
vote
1
answer
66
views
Defining a Sphinx MathJax macro with arguments throws error "MathJax: Invalid option"
I'm running Sphinx 4.5.0 in Python 3.10 and trying to write a MathJax macro that takes parameters. I've found examples that show how to do this (example 1 mathjax3_config)
, but when I copy them to ...
- 83
1
vote
0
answers
125
views
The SQLAlchemy @hybrid_property decorator creates an exception in Sphinx autodoc and the property is not documented
I have a SQLAlchemy @hybrid_property like this:
@hybrid_property
def number_of_lightnings(self) -> int:
"""
Blah, blah, blah....
when I generate the docs with Sphinx I get ...
1
vote
0
answers
62
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 ...
- 488
2
votes
0
answers
60
views
sphinxcontrib-bibtex and sphinx-multiversion
I have a strange bug when building our documentation using sphinxcontrib-bibtex and sphinx-multiversion.
In my docs/source/conf.py I have
from pathlib import Path
extensions = [
"...
- 1,897
1
vote
0
answers
69
views
Is it possible to combine some information written manually (including images) into the auto generated docs?
I have some auto generated documentation using Sphinx
I would like to overwrite one of the pages with a manually written page that includes additional images, which isn't possible in the autodoc from ...
- 169
2
votes
0
answers
40
views
How to resolve the URL to a class/function/method in a sphinx extension
Background
I'm designing a Sphinx extension called sphinx-uml that tries to improve sphinx-pyreverse. The goal is to output a navigable UML diagram (when you click a class/method/function, you go to ...
- 395
0
votes
1
answer
52
views
Code block partially highlighted in Sphinx
In my Sphinx documentation I have the following code-block:
.. code-block:: python
import logging
logging.getLogger('mymodule').setLevel(logging.INFO)
but when the documentation is rendered ...
- 973
1
vote
0
answers
110
views
readthedocs failing on maturin builds
I have a primary python project that has a dependency of another python lib which is a maturin wrapped rust crate.
My 'readthedocs' script is failing on the lib using maturin with:
Caused by:
...
- 8,185
1
vote
1
answer
73
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
118
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
51
views
Is there a way to disable permalinks conditionally in sphinx?
I know there is an option in Sphinx called html_permalinks which can be set to False in the conf.py file. But this disables permalinks completely.
I'm looking for a way to exclude certain levels of ...
- 58
0
votes
0
answers
44
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
37
views
sphinx does not build docs except gallery examples when sphinx-gallery extention is loaded
I generate a sphinx documentation of a python project, which includes a sphinx-gallery.
When I update sources/index.rst, sources/my_class.rst or the correspoding my_class.py, the corresponding html is ...
- 2,234
0
votes
2
answers
82
views
How to merge Doxygen snippets?
I have a project using Doxygen, Breathe, and Sphinx for documentation. The hardcoded example snippets of code in the documentation have become a pain to maintain, as the project is constantly evolving....
- 672
0
votes
0
answers
97
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
0
votes
1
answer
124
views
How should I document Python constants so they are reflected in Intellisense and Sphinx?
I have a file called constants.py where I store all my constants, such as paths PATH_DATASETS = "data/datasets/" or values WIDTH = 416.
They are use multiples times in the code, sometimes as ...
- 1
7
votes
4
answers
368
views
Documenting a script step by step with Sphinx
I am documenting a python library with Sphinx.
I have a couple of example scripts which I'd like to document in a narrative way, something like this:
#: Import necessary package and define :meth:`...
- 2,234
0
votes
0
answers
33
views
ToC lists subsections for Python but not for MatLab Code
I am testing Sphinx to help documenting MatLab (and Python sometimes) code using the comments. After a lot of struggling, I managed to get both working but noticed that I don't get sub-levels on the ...
- 21
3
votes
1
answer
143
views
Sphinx - autodoc imported data with own docstring
The situation
I want to use the Sphinx autodoc features to document a Python API that is implemented in the following way.
I have a module that is used to expose various symbols (functions, constants, ...
- 87
0
votes
0
answers
50
views
How do you set the same row height for all rows in a table created with sphinx? (LaTeX)
How can I modify the latex_preamble to force all rows in a table to have the same height? With Table 1 it's hard to spot, but if you look at Table 2, you can see the first and last row have extra ...
- 788
0
votes
0
answers
46
views
Why does sphinx-quickstart honor conf.py_t but not conf.py.jinja?
This is my ./_templates/conf.py.jinja:
# Configuration file for the Sphinx documentation builder.
# -- Project information -----------------------------------------------------
project = '{{ project ...
- 6,435
0
votes
0
answers
53
views
Writing a custom sphinx extension to color CSV table cells
I'm writing a custom sphinx extension to color a cell in a given column based on a category. The extension needs to work for producing html and pdf. I'm about 95% of the way there, however, my ...
- 788
1
vote
0
answers
44
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
2
votes
0
answers
41
views
Adding a toctree level inside a file
When using the following with the autosummary extension of sphinx,
Module
======
Section
-------
Foo
.. autosummary::
:toctree:
~mypkg.Bar
I naturally get the following hierarchy:
Module
└...
- 51
1
vote
0
answers
47
views
Why does Sphinx generate indentation errors when attempting to include numpy arrays?
I am attempting to generate documentation using Sphinx based on docstrings. When I attempt to include an array for output (which spans multiple lines, and also has indents on all but the first line) I ...
- 73
0
votes
0
answers
61
views
Sphinx autosummary - module name repeated instead of function names
I'm using sphinx-build 7.4.7
Python 3.9.11
I'm trying the most basic build. Just a module with a file of functions. However, when I make the html and look at the module, the webpage has simply repeats ...
- 31
0
votes
0
answers
67
views
How can I adjust alignment in a sphinx PDF table?
I want to control the vertical and horizontal alignment of the cells in a table generated with sphinx and texlive, and I want to be able to force a new line in my csv file. I'm using python==3.13.2 ...
- 788
1
vote
1
answer
52
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
54
views
Shorten Site's public URL with Sphinx
I'm building a website with Sphinx and want to shorten the public URL. By default, the Sphinx "make html" command places files in a "/build/html/" directory. My script then rsyncs ...
- 1
1
vote
0
answers
53
views
How to disable duplicate parameter documentation in Sphinx / ReadTheDocs theme
When documenting Python code using Sphinx (v8.2.3), the parameters of the class' initializer __init__(self, ...) are documented two times:
in the class' description
in the dunder init method
I ...
- 16.5k
0
votes
0
answers
57
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
0
answers
152
views
Sphinx warning image file not readable
I am developing a custom Sphinx directive that generates an image file and then adds an image node for that file with
img_node = nodes.image(uri=image_uri)
That basically works and I can see the ...
- 1
2
votes
0
answers
81
views
How to combine MkDocs with pybind11 modules?
I'm trying to generate a documentation site for a Python API which is created with pybind11 using MkDocs. This API has also a .cpp API which is generated well.
This is my C++ common header code:
#...
- 21
0
votes
0
answers
42
views
How to have entire attention admonition on one page with sphinx's LaTeX output
I am using sphinx 8.1.3 with LaTeX as the output format. In my documents I am using the "attention" admonition feature of sphinx which shows a colorful block of text that directs the reader ...
- 13
1
vote
0
answers
55
views
Custom reference role in Sphinx
I'm trying to create a custom Sphinx role that allows me to type:
:req:`5.1 My requirement`
that is then translated into the equivalent of
:ref:`[5.1] <requirements:5.1 My requirement>`
My ...
- 1,710
0
votes
1
answer
77
views
Can Sphinx apidoc automatically split huge module to several pages?
I'm using Sphinx with autodoc to generate documentation for very huge Python module (about 1000 classes, don't ask me why, this is legacy code).
Resulting HTML is painful to view and regularly crashes ...
- 875
2
votes
2
answers
45
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,927
1
vote
1
answer
59
views
Sphinx command line utilities
I want to do something different in a shell script when sphinx_build gives a warning and I run sphinx_build in strict mode, but I do not seem to get a non-zero return code. Is there any way to detect ...
- 2,927
4
votes
1
answer
162
views
How to document imported constants with Sphinx
The autodoc automodule documentation says
Note that attributes from imported modules will not be documented, because attribute documentation is discovered by parsing the source file of the current ...
- 488
0
votes
1
answer
65
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 ...
0
votes
0
answers
38
views
Is there a way to generate 'File List' in Sphinx for Python?
Is there a way to generate "File lists" in Sphinx documentation for a Python repository similar to Doxygen File lists generated for C++ as shown below?
Doxygen File lists
I've tried the '...
- 1