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
252
votes
12 answers

Using Sphinx with Markdown instead of reST

I hate reST but love Sphinx. Is there a way that Sphinx reads Markdown instead of reStructuredText?
digi604
  • 2,636
  • 2
  • 17
  • 5
222
votes
6 answers

Automatically document all modules recursively with Sphinx autodoc

I'm trying to use Sphinx to document a 5,000+ line project in Python. It has about 7 base modules. As far as I know, In order to use autodoc I need to write code like this for each file in my project: .. automodule:: mods.set.tests :members: …
Cory Walker
  • 4,809
  • 4
  • 28
  • 32
145
votes
6 answers

Adding a cross-reference to a subheading or anchor in another page

How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
Sue Walsh
  • 1,453
  • 2
  • 10
  • 6
142
votes
10 answers

sphinx-build fail - autodoc can't import/find module

I'm trying to get started with Sphinx and seem to have relentless problems. Command: docs/sphinx-quickstart I answer all the questions and everything works fine. Command: docs/ls Everything looks normal. Result: build Makefile source Command:…
Rico
  • 5,692
  • 8
  • 46
  • 63
136
votes
8 answers

What is the correct way to document a **kwargs parameter?

I'm using Sphinx and the autodoc extension to generate API documentation for my Python modules. Whilst I can see how to nicely document specific parameters, I cannot find an example of how to document a **kwargs parameter. Does anyone have a good…
jkp
  • 78,960
  • 28
  • 103
  • 104
133
votes
3 answers

Link to class method in Python docstring

I want to add a link to a method in my class from within the docstring of another method of the same class. I want the link to work in Sphinx and preferentially also in Spyder and other Python IDEs. I tried several options and found only one that…
saroele
  • 9,481
  • 10
  • 29
  • 39
126
votes
8 answers

Can sphinx link to documents that are not located in directories below the root document?

I am using Sphinx to document a non-Python project. I want to distribute ./doc folders in each submodule, containing submodule_name.rst files to document that module. I then want to suck those files into the master hierarchy to create a spec for…
mc_electron
  • 1,503
  • 3
  • 11
  • 13
123
votes
6 answers

How to use Sphinx's autodoc to document a class's __init__(self) method?

Sphinx doesn't generate docs for __init__(self) by default. I have tried the following: .. automodule:: mymodule :members: and ..autoclass:: MyClass :members: In conf.py, setting the following only appends the __init__(self) docstring to…
Jacob Marble
  • 28,555
  • 22
  • 67
  • 78
114
votes
2 answers

How to create a nested list in reStructuredText?

I am trying to create a properly nested list using the following code (following Sphinx and docutils docs): 1. X a. U b. V c. W 2. Y 3. Z I expect this to result in two OLs but I get the following output instead:
    …
muhuk
  • 15,777
  • 9
  • 59
  • 98
103
votes
5 answers

How to document Python code using Doxygen

I like Doxygen to create documentation of C or PHP code. I have an upcoming Python project and I think I remember that Python doesn't have /* .. */ comments, and also has its own self-documentation facility which seems to be the pythonic way to…
Hanno Fietz
  • 30,799
  • 47
  • 148
  • 234
99
votes
1 answer

Sphinx error: Unknown directive type "automodule" or "autoclass"

I need to document my Python project using Sphinx. But I can't use autodoc. When I config my project I select the option "extension autodoc", but now if I use .. autoclass:: Class I get an error: ERROR: Unknown directive type "autoclass" I…
edgarzamora
  • 1,472
  • 1
  • 9
  • 17
98
votes
4 answers

Format text in a link in reStructuredText

How do you format text within a denoted link in reStructuredText? Specifically, I wish to generate the following HTML from my rst: optparse.OptionParser documentation…
gotgenes
  • 38,661
  • 28
  • 100
  • 128
93
votes
8 answers

How to document a module constant in Python?

I have a module, errors.py in which several global constants are defined (note: I understand that Python doesn't have constants, but I've defined them by convention using UPPERCASE). """Indicates some unknown error.""" API_ERROR = 1 """Indicates…
skyler
  • 8,010
  • 15
  • 46
  • 69
86
votes
4 answers

WARNING: document isn't included in any toctree for included file

I'm getting the warning: WARNING: document isn't included in any toctree for files that exist in the document because they've been explicitly included. So I have the index file: .. toctree:: :maxdepth: 2 pages/0010-foo …
NickChase
  • 1,442
  • 3
  • 15
  • 23
82
votes
2 answers

How would I cross-reference a function generated by autodoc in Sphinx?

I am using the Sphinx autodoc feature to generate documentation based on the docstrings of my Python library. The syntax for cross referencing is found here A label must precede the section in order to allow that section to be referenced from other…
Matthew Stamy
  • 1,114
  • 1
  • 7
  • 9
1
2 3
…
99 100