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
41
votes
4 answers

How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?

I have a document with many headings and sub-headings. Further into the text I want to link back to one of the headings. How can I do this without the redundancy of :ref: labels? The contents seems to pick up headers just fine. I was hoping for…
caduceus
  • 1,542
  • 2
  • 16
  • 21
41
votes
8 answers

Using Sphinx to write personal websites and blogs

Sphinx is a Python library to generate nice documentation from a set of ReST formatted text files. I wonder if any one has written Sphinx plugins to make it generate personal websites and blogs. Especially for blogs, there needs to be a way to…
Sridhar Ratnakumar
  • 81,433
  • 63
  • 146
  • 187
40
votes
2 answers

Documenting class attributes with type annotations

I want to autogenerate documentation to my code from docstrings. I have some basic class meant to store some data: class DataHolder: """ Class to hold some data Attributes: batch: Run without GUI debug (bool): Show…
Djent
  • 2,877
  • 10
  • 41
  • 66
40
votes
9 answers

How to create a PDF-out-of-Sphinx-documentation-tool

Followed this link to try and generate pdf from Sphinx: https://www.quora.com/How-to-create-a-PDF-out-of-Sphinx-documentation-tool $ sphinx-build -b pdf source build/pdf Error: Cannot find source directory `/Users/seb/mydocs/source'. $ make…
niceseb
  • 493
  • 1
  • 4
  • 11
40
votes
4 answers

How to expand all the subsections on the sidebar toctree in Sphinx?

I was wondering if there is a way to expand all the subsections under the headers that are included in the index.rst file? As an example, here is how it is: Section 1 Section 2 Section 3 And here is how I would like it to be: Section 1 Subsection…
Joe D
  • 401
  • 4
  • 3
39
votes
2 answers

Sphinx, using automodule to find submodules

When using sphinx's automodule (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html), I simply write in a .rst file: .. automodule:: my_module :members: It documents my_module fine, but it doesn't find the inner modules like…
Christopher Dorian
  • 2,163
  • 5
  • 21
  • 25
37
votes
5 answers

Referencing figures with numbers in Sphinx and reStructuredText

When writing RST that will be processed with Sphinx, I can't get Sphinx LaTeX output to use figure numbers when referencing figures. For instance, this code: The lemmings are attacking, as can be seen in :ref:`figlem`. .. _figlem: .. figure::…
Lucas
  • 6,328
  • 8
  • 37
  • 49
37
votes
2 answers

reStructuredText in Sphinx and Docstrings: single vs. double back-quotes or back-ticks difference

From the documentation, it appears that the double back-quote is used for literals, while the single back-quote is used when there is code text to be intepreted. This would lead me to to write the docstring for method f() below: class A(B): …
Jeet
  • 38,594
  • 7
  • 49
  • 56
37
votes
4 answers

Sphinx: force rebuild of html, including autodoc

Currently, whenever I run sphinx-build, only when there are changes to the source files are the inline docstrings picked up and used. I've tried calling sphinx-build with the -a switch but this seems to have no effect. How can I force a full rebuild…
Phillip B Oldham
  • 18,807
  • 20
  • 94
  • 134
37
votes
3 answers

Markdown output for Sphinx based documentation

I found myself with a use case, where in addition to generating HTML and PDF from my Sphinx based documentation sources, I would also like to generate a Markdown version of the reStructuredText source files. My preliminary research didn't find any…
Pedro Romano
  • 10,973
  • 4
  • 46
  • 50
36
votes
1 answer

Retaining inline code inside references in Sphinx

In Sphinx, if I have the following heading declaration: .. _somestuff: ``this is code``, this is not! ============================== It renders, like this:     this is code, this is not! Which is good, but, if I use the reference, e.g: Have a look…
tjm
  • 7,500
  • 2
  • 32
  • 53
36
votes
8 answers

How to embed Plotly graphs in Sphinx documentation and nbsphinx

I tried using nbsphinx to embed a Jupyter notebook containing plotly plots, but the plots don't show up in the documentation, even though they look fine on the Jupyter notebook. How can I embed a plotly graph in Sphinx documentation? I could…
bluprince13
  • 4,607
  • 12
  • 44
  • 91
35
votes
2 answers

How to add extra whitespace between section header and a paragraph

I want to have more space between the header and the paragraph and between the paragraphs. I doesn't want this to be a global setting but I want to use it where and when required. Appreciate any suggestions.
Aravind Yarram
  • 78,777
  • 46
  • 231
  • 327
35
votes
4 answers

Can Sphinx napoleon document function returning multiple arguments?

I am trying to use the Google code style to document a function that I then use sphinx with the napoleon extension to create documentation for. The function is unusual in that is returns two arguments. I don't think napoleon handles this. If so,…
MrCartoonology
  • 1,997
  • 4
  • 22
  • 38
35
votes
2 answers

How do I have multiple versions of my doc with sphinx?

Like the documentation of python or django, how do I have multiple versions of my doc with sphinx ? I saved my doc on git, and I want my user to be able to see documentation for different version like v2.7,v3.4, etc Thank you for the help
Guillaume Vincent
  • 13,355
  • 13
  • 76
  • 103
1 2 3
…
99 100