Stack Overflow
Stack Overflow

Questions tagged [python-sphinx]

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. Sphinx is especially suitable for Python documentation, but it is a general-purpose tool that can be used to document anything.

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well.

Sphinx is under constant development. The following features are present, work fine and can be seen “in action” in the Python documentation:

  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.

  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information.

  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children.

  • Automatic indices: general index as well as a module index.

  • Code handling: automatic highlighting using the Pygments highlighter.

  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more.

Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.

See also:

3663 questions
2
votes
0 answers

TypeVar object not documented as expected in method signature

The problem I'm wanting to document some modules in a package I'm developing using Sphinx. Throughout the modules I've imported some TypeVar objects from a module within the package - these objects refer to different types of data objects. I've done…
James Laidler
  • 21
  • 1
2
votes
0 answers

Set a default option for a given directive in Sphinx

In Sphinx, is there a way to set a default value for a directive option in conf.py, so that it is always used whenever I use that directive? In particular, I am using autosummary, and I always want :toctree: to be set so that I don't have to…
asmeurer
  • 86,894
  • 26
  • 169
  • 240
2
votes
1 answer

How can I change the file path of files referenced via the download role to not use a hashed folder?

I want to provide a link to a file in my project, but I want this link to be human readable and perma-ish. Doing this: Link to file for reference :download:`myfile.json <../myproject/myfile.json>`. Generates a link that looks like…
red888
  • 27,709
  • 55
  • 204
  • 392
2
votes
1 answer

Furo Sphinx theme keeps uppercasing too much in API documentation

I am facing the same problem discussed in this question: Furo Sphinx theme uppercases too much in API documentation. However, the accepted solution did not work, it seems that the Furo template is somehow overwriting the custom.css: I appreciate…
Paulo Araujo
  • 61
  • 8
2
votes
1 answer

Furo Sphinx theme uppercases too much in API documentation

I am a beginner in documentation with Sphinx. I wanted to produce numpy style documentations. Therefore, I used numpydoc extension. Numpy uses pydata theme, however I chose furo. I understand that there will be some differences in appearance, but I…
Kaan Güven
  • 45
  • 6
2
votes
1 answer

Sphinx and RST: How to move caption BELOW table, just like in figures and other clever things?

I have created a grid table with directives: ..table:: *Table 1: Power Connector* :align: center This is the result: The big question is how to move the caption Table 1: Power Connector BELOW the table, is there some trick? I am sure there is,…
Dare The Darkness
  • 103
  • 1
  • 8
2
votes
1 answer

Readthedocs adding html_logo causes type error

I have some documentation deployed on readthedocs.io. It was working fine until I added the following line to my conf.py: html_logo = '_static/logo.png', As soon as I try to build the project on readthedocs it fails with the following…
Computroniks
  • 85
  • 1
  • 11
2
votes
3 answers

Unable to build link to document due to missing title (in index)

I am using sphinx for documentation. When I am using "make confluence", I am getting the below warnings from the index.rst file. How can I remove these warnings? Also, Table of content is not working in confluence due to these warning but the…
Divyank
  • 811
  • 2
  • 10
  • 26
2
votes
0 answers

Cannot find relative path '../..' outside of root directory in Sphinx restructuredText: 'unknown document error'

Even though I checked the relative path a million times (it is correct as measured from the document location wherein the reference is stated), still the error is thrown upon pushing the docs to AWS CodeBuild: Warning, treated as…
Andreas L.
  • 3,239
  • 5
  • 26
  • 65
2
votes
1 answer

How to import Markdown with Sphinx and myst-parser into Readthedocs?

In my docs/source/conf.py I have this code: extensions = [ "sphinx.ext.autodoc", "myst_parser", ] source_suffix = ['.rst', '.md'] All my files are in Markdown, not in reStructuredText. On ReadTheDocs, the initial build was successful…
ljyip
  • 41
  • 5
2
votes
1 answer

Read The Docs not updating

Read The Docs seems to be stuck on an old version of my docs and whatever I do in won't update. I even tried deleting the project from Read The Docs completely and reimporting the github repo - it still shows the old version. The builds show as…
chasmani
  • 2,362
  • 2
  • 23
  • 35
2
votes
1 answer

How to make Sphinx recognize the `:param` element?

I want to use Sphinx to generate html documents, and although I can generate them successfully, Sphinx does not recognize elements like :param content:. Wrong document Correct document Here you can see the specific code file, using . \make.bat…
Andy
  • 1,077
  • 1
  • 8
  • 20
2
votes
1 answer

how to include pdf 1.6 files in sphinx

We use libreoffice to generate pdf-figures from odg files (automatically via makefile) and include these in documentation generated by sphinx that via LaTeX ultimately produces a pdf file. This works nicely. However, starting with libreoffice 7,…
pba
  • 524
  • 3
  • 13
2
votes
1 answer

"Searching..." takes forever on readthedocs when the phrase is not present on the page

When I search for a phrase which is not present on the readthedocs page, I get the message: "Searching...", which will take forever. On the contrary, when I search for some known phrase, I get the results within a second. I have looked into page's…
Maria
  • 176
  • 1
  • 11
2
votes
2 answers

nbsphinx causes build to fail when building Jupyter Notebooks

Details I am getting a build failure of my read-the-docs that I don't understand. The assertion of "verbatim" in line 2151 of nbsphinx.py is causing the build failure. So the build fails when I try to include the Jupyter Notebook tutorials I…
Logan Pearce
  • 51
  • 4
1 2 3
…
99 100