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
2 answers

SPHINX - numref works for HTML but not for LaTex

I am working on a Sphinx project for software documentation, which includes a lot of figures. I use 'numref' for referring to the pictures. In HTML it works fine. In LaTex I get Fig. ?? There are only a few issues on numref on the web and the…
Niels de Nies
  • 31
  • 4
2
votes
0 answers

Problem with blank line in interactive session

In one of the sections of one technical document that I'm writing using reStructuredText I want to include a interactive session and this output. Example: >>> help(module) asdasd asdasd asdasd When I process with sphinx-build to build…
ccarmona
  • 45
  • 5
2
votes
0 answers

Autodoc class with multiple signatures

I have the following http client class class MyClient: """Class docstring""" @overload def __init__(self, url): ... @overload def __init__(self, *, scheme, auth, host, port, path): ... def __init__(self, url=None, **kwargs): ... and…
warownia1
  • 2,771
  • 1
  • 22
  • 30
2
votes
0 answers

How to skip Python source files in readthedocs Sphinx build

How can I tell readthedocs not to load any Python files located at top root folder? Background: I would like readthedocs to build Sphinx documentation for a Blender Python add-on, hosted on github. I have created docs folder in the repository for…
Tuomo Keskitalo
  • 21
  • 2
2
votes
1 answer

restructuredtext link to other rst file menu anchor

With this structure: $ tree . ├── Editors.rst └── Tool_vim.rst From Editor.rst file I want to do a link to the Tool_vim.rst file. I get it with: Follow install from :doc:`Tool_linux_install` But on Tool_linux_install.rst I have a menu with ..…
user3313834
  • 7,327
  • 12
  • 56
  • 99
2
votes
1 answer

Sphinx rst2pdf and role directives

In a reStructuredText on Sphinx 2.x, I want to put a content that changes depending on the output format. In any source document, say, index.rst, add the following lines: .. role:: pdf(raw) :format: pdf .. role:: latex(raw) :format: latex ..…
Culip
  • 559
  • 8
  • 24
2
votes
0 answers

Sphinx and Markdown: hyperlinks to section in a different file

I'm trying to convert Markdown files to html using Sphinx and I am having trouble with links that point to a section in a different Markdown file. Original Markdown (reference to section): [Kubernetes…
garciadeblas
  • 116
  • 1
  • 7
2
votes
0 answers

Sphinx Latex break line autodoc

I am making my python docs with sphinx-apidoc. But some text seems messed up because the line does not break in certain cases. I have tried to set latex_elements on config.py with preamble, but the result is the same. You can also see that the…
Luis Coimbra
  • 171
  • 1
  • 1
  • 8
2
votes
1 answer

nbsphinx syntax highlighting on readthedocs

I have a readthedocs sphinx documentation which uses nbsphinx to display jupyter notebooks. When I build the documentation locally with autobuild, I have syntax highlighting in the code cells in the jupyter notebook. But on readthedocs, the code…
Randrian
  • 1,055
  • 12
  • 25
2
votes
1 answer

Sphinx: customize sidebar section titles

I am documenting my Python project with Sphinx. As some of my documentation pages are rather long, I would like to have both a local and a global table of contents in the sidebar. I achieve achieve this via html_sidebars = { '**': ['localtoc.html',…
Samufi
  • 2,465
  • 3
  • 19
  • 43
2
votes
1 answer

Where are Sphinx autosummary templates for functions?

I am building documentation for a project using the Sphinx extension autosummary. I would like to make a very slight change to the default templates that the documentation alludes to. I was able to copy and modify the templates for base.rst,…
Jonathan Lym
  • 113
  • 8
2
votes
1 answer

Getting multiline docstring equations to be displayed in Sphinx. Potential bug in Sphinx?

There is the following piece of code on the official Sphinx documentation: .. math:: :nowrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray} I tried for a long time to get it to work, until I…
user719220
  • 71
  • 2
2
votes
1 answer

Sphinx - Use ellipses (…) in code-block snippets

Consider you document a long code snippet and you want to represent repetitive values and lines in it with ellipses … (…) and vertical ellipses ⋮ (⋮). Here's an example record in JSON. There are 26 kids and you don't want to…
Culip
  • 559
  • 8
  • 24
2
votes
1 answer

How to add inheritance diagram to all modules in Sphinx?

So I've been trying to get Sphinx to generate inheritance diagrams for all submodules / classes when generating .rst files through sphinx-apidoc, similar to this example. But I have not found any built-in features to do this in Sphinx. The nearest…
joneivinds
  • 61
  • 5
2
votes
0 answers

How to document metaclass members in Sphinx?

I would like to document the metaclass members of a class because those are basically class methods and class attributes. Here's a minimal example: """Module docstring .. autosummary: :toctree: _autosummary Foo """ class MetaFoo(type): …
Jaakko Luttinen
  • 695
  • 2
  • 7
  • 21
1 2 3
…
99 100