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
1 answer

How to properly define a new admonition in Sphinx?

With Sphinx it is easy to write extensions, but is it very hard to extend Sphinx in the proper way. I would like to define a custom Admonition so I have: class exercise(nodes.Admonition, nodes.Element): pass class…
nowox
  • 25,978
  • 39
  • 143
  • 293
2
votes
0 answers

Multiple (Nested) Roles in a Glossary

in my Sphinx docs I would like to create a glossary, potentially containing :math:, or other roles: .. glossary:: :math:`f(x)` Description Is there any way to reference this entry with a text that has the same style as the glossary…
John Titor
  • 461
  • 3
  • 13
2
votes
1 answer

How do I scale a graphviz diagram in Sphinx

I have a GraphViz diagram embedded in Sphinx, such as .. graphviz:: :caption: My diagram digraph { a -> b -> c -> d } How do I scale it for display in the HTML generated by Sphinx? It doesn't accept a :scale: directive after the…
Lars Ericson
  • 1,952
  • 4
  • 32
  • 45
2
votes
1 answer

How can I include a hyperlink reference inside an inline literal in reStructuredText?

I am using Sphinx with reStructuredText, and I’d like to include a hyperlink inside an inline literal. However, predictably, if I write The result has type ``Foo_ -> Bar_``. .. _Foo: Information about ``Foo``. .. _Bar: Information about…
Alexis King
  • 43,109
  • 15
  • 131
  • 205
2
votes
1 answer

Code Formatting for the ReadTheDocs System

I'm using Read the Docs for the first time. I'm writing docs for a command line system, and my "code samples" include a log of shell output. The shell output ends up looking like this That is -- the service (or my use of it?) is trying to format…
Alana Storm
  • 164,128
  • 91
  • 395
  • 599
2
votes
1 answer

Sphinx docs including unit test output

This is a how-to/best-practice question. I have a code base with a suite of unit tests run with pytest I have a set of *.rst files which provide explanation of each test, along with a table of results and images of some mathematical plots Each time…
user3482876
  • 249
  • 2
  • 11
2
votes
1 answer

Should Sphinx be able to document instance attributes in a class?

I'm finding conflicting and often dated information so hoping someone can clear this up. I'd like to document something like this using Sphinx: class MyClass: """ MyClass, which is documented with a docstring at the class level """ …
Andrew
  • 459
  • 5
  • 15
2
votes
1 answer

How to get the same output from sphinx napoleon and numpy style docs as with the default rst way?

If I take the very simple python file: def magic_function(parameter1): """ Do magic with parameter1. :param parameter1: The first of all paramters :type parameter1: nd_array """ return parameter1 I get the type right after…
NOhs
  • 2,780
  • 3
  • 25
  • 59
2
votes
1 answer

Could not import extension ... SphinxDirective

I am trying to test the sphinx extension TODO from https://sphinx.readthedocs.io/en/master/development/tutorials/todo.html#writing-the-extension However, this import "from docutils.parsers.rst import SphinxDirective" does not work, giving "Extension…
Miro Iliaš
  • 419
  • 5
  • 16
2
votes
1 answer

"fails to import module" when running the test_data example of sphinxcontrib-matlabdomain on Ubuntu 18.04

I'm trying to run the example/demo given on sphinxcontrib-matlabdomain pypi site but autodoc module fails to import the matlab example files. I setup the sphinx environment with sphinx-quickstart. OS is Ubuntu 18.04. My directory structure looks…
GeezleGit
  • 23
  • 3
2
votes
0 answers

breathe cannot find C# interface

I'm trying to use doxygen, breathe and sphinx to generate documentation for a C# library. This is under Windows. The basic directory structure is: docs index.rst conf.py xml xml output from doxygen I'm running into the following…
Mark Olbert
  • 6,584
  • 9
  • 35
  • 69
2
votes
0 answers

sphinx-apidoc generate documentation for class re-exported in __init__.py

In mypkg/_core.py I have class SomeClass: """Here is my class.""" def __init__(self, x: int): self.x = x In __init__.py I have from mypkg._core import SomeClass I figure there's a default configuration to avoid documenting…
Hatshepsut
  • 5,962
  • 8
  • 44
  • 80
2
votes
0 answers

How do I create dependency diagrams in Sphinx?

I've just started working with Sphinx and I need to generate a diagram showing the dependencies between different functions (some of which may be part of an object). Sphinx can produce very nice inheritance diagrams, but I need to show the…
SqrtPi
  • 121
  • 2
  • 11
2
votes
1 answer

How to Hide Code cells When converting a Jupyter Notebook into Sphinx Doc using nbsphinx

I'm new to Sphinx documentation, and I am trying to convert a Jupyter Notebook into Sphinx docs using Nbsphinx. Especially, I want to hide the code cells (not their outputs), but I could not make it using templates that I found for Jupyter…
KYigit
  • 39
  • 3
2
votes
1 answer

Sphinx does not show local headings in TOC

When generating sphinx documentation using the default settings (including the Alabaster theme), the TOC sidebar only shows the top level headings for the entire document. It used to show the second-plus level headings for the current page. How do I…
Matthew
  • 2,593
  • 22
  • 25
1 2 3
…
99 100