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

What are the main differences of Sphinx and Doxygen?

I want to prepare a documentation for a collection of projects, modules and libraries in the field of computer vision (mostly written in c++). To this end I had a look on OpenCV documentation and as you may know OpenCV 2.4.x documentation is based…
Ali Mirzaei
  • 1,496
  • 2
  • 16
  • 27
32
votes
6 answers

Sphinx Autodoc skip member from docstring

I am documenting a class with Sphinx and simple want to skip one of the classes members: class StatusUpdateAdapter(logging.LoggerAdapter): """ """ def __init__(self, status_update_func, logger, extra={}): """ """ …
Colton Leekly-Winslow
  • 803
  • 1
  • 8
  • 14
32
votes
4 answers

How to document an exception using Sphinx?

I can't seem to figure out how to document exceptions using Sphinx. I've tried the following: def some_funct(): """ :raises: ExceptionType: Some multi-line exception description. """ def some_funct(): """ :raises:…
siebz0r
  • 18,867
  • 14
  • 64
  • 107
32
votes
9 answers

How can I use Sphinx' Autodoc-extension for private methods?

I am using Sphinx for documenting my python project. I have the autodoc extension enabled and have the following in my docs. .. autoclass:: ClassName :members: The problem is, it only documents the non-private methods in the class. How do I…
cnu
  • 36,135
  • 23
  • 65
  • 63
31
votes
2 answers

Change the favicon of the Sphinx Read The Docs theme?

I'm already using a custom css to override some of the styles of the theme using def setup(app): app.add_css_file('custom.css') This works fine. What other app. functions are available? I can't find any documentation. I'm looking for the…
Paul Meems
  • 3,002
  • 4
  • 35
  • 66
31
votes
2 answers

How can I prevent sphinx from displaying the full path to my class?

I have a project structure like this: package/ __init__.py module.py __init__.py contains: from .module import Class module.py contains: class Class: pass Using sphinx-apidoc -o package/docs/ package/ and sphinx-build package/docs/…
Aran-Fey
  • 39,665
  • 11
  • 104
  • 149
31
votes
3 answers

What is the relationship between docutils and Sphinx?

There seems to be a plethora of documentation tools for Python. Another one that I've run across is epydoc. It seems like Sphinx is the de facto standard, because it's used to generate the official Python docs. Can someone please sort out the…
allyourcode
  • 21,871
  • 18
  • 78
  • 106
30
votes
2 answers

Sphinx PDF themes

Does the Sphinx documentation tool offer different PDF themes like it offers different HTML themes? I Googled the issue but can't find an answer, which leads me to believe the answer is 'no'. Still, i thought i'd ask here. Thanks.
araichev
  • 748
  • 1
  • 6
  • 14
30
votes
2 answers

Substitutions inside Sphinx code blocks aren't replaced

In this reST example meant to be rendered by Sphinx, |yaco_url| doesn't get replaced because it's in a code-block: .. |yaco_url| replace:: http://yaco.es/ You can use wget to download it: .. code-block:: console $ wget…
Danny Navarro
  • 2,733
  • 1
  • 18
  • 22
30
votes
7 answers

How to use Python to programmatically generate part of Sphinx documentation?

I am using Sphinx to generate the documentation for a project of mine. In this project, I describe a list of available commands in a yaml file which, once loaded, results in a dictionary in the form {command-name : command-description} for…
mac
  • 42,153
  • 26
  • 121
  • 131
30
votes
1 answer

How can I add a custom footer to Sphinx documentation?

If I have some documentation, like for example Galleria's documentation, how can I set it up so that when I run the make html command it will add a custom footer to each page? I saw that I could potentially use the LaTeX preamble section of conf.py…
cwd
  • 53,018
  • 53
  • 161
  • 198
30
votes
3 answers

Linking back to a source code file in Sphinx

I am documenting a Python module in Sphinx. I have a source code file full of examples of the use of my module. I'd like to reference this file. It is too long to inline as continuous code. Is there a way to create a link to the full source file,…
Eli S
  • 1,379
  • 4
  • 14
  • 35
29
votes
2 answers

How to make an internal hyperlink in Sphinx documentation

How to make an internal hyperlink in Sphinx documentation? I am using: :role:`target` But it is not working.
ajax-ie
  • 293
  • 1
  • 4
  • 7
29
votes
5 answers

sphinx, restructuredtext: set color for a single word

Is there a way to set the color of single words (or characters) in sphinx? I'm pretty sure there should be some markup tag, like HTML's font tag.
Adam Matan
  • 128,757
  • 147
  • 397
  • 562
29
votes
7 answers

How to properly write cross-references to external documentation with intersphinx?

I'm trying to add cross-references to external API into my documentation but I'm facing three different behaviors. I am using sphinx(1.3.1) with Python(2.7.3) and my intersphinx mapping is configured as: { 'python': ('https://docs.python.org/2.7',…
Gall
  • 1,595
  • 1
  • 14
  • 22
1 2 3
…
99 100