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

Emit reStructuredText from sphinx autodoc?

CPython doesn't use autodoc for its documentation - we use hand-written prose. For PEP 3144 (the ipaddress module), I'd like to use sphinx-apidoc to generate the initial reference documentation. That means I want to run a two-pass operation: Use…
ncoghlan
  • 40,168
  • 10
  • 71
  • 80
24
votes
3 answers

How do I use Sphinx with Cython?

I have recently Cythonized a project of mine by renaming all of the modules (except for the top-level __init__.py) to *.pyx, and by putting ext_modules = [Extension('foo', ['foo.pyx'])] in setup.py. Building and installing works fine. However,…
Dan Stahlke
  • 1,417
  • 1
  • 15
  • 20
23
votes
9 answers

How to force Sphinx to use Python 3.x interpreter

I try to create documentation for a project written with Python 3.x. Sphinx is the tool I want to use and, according to the official site, its last version 1.1.2 is compatible with Python 3.1+. My OS is Archlinux, a Linux distribution which uses…
suizokukan
  • 1,303
  • 4
  • 18
  • 33
23
votes
2 answers

Use Sphinx autosummary recursively to generate API documentation

I want to use Sphinx's autosummary extension and templates to generate API docs recursively from docstrings. I want separate pages for each module, class, method, property and function. But it doesn't detect my templates at all. In fact, if I just…
Hameer Abbasi
  • 1,292
  • 1
  • 12
  • 34
23
votes
2 answers

How can I show pictures of keyboard keys in-line with text with Sphinx?

In my Sphinx documentation, I'd like to show pictures of keyboards keys when I refer to them in the restructured text. For example, if I say: Hit the Enter key. I'd like to show a picture of the Enter key in-line, instead of just the word Enter. I…
bluprince13
  • 4,607
  • 12
  • 44
  • 91
23
votes
1 answer

Get variables in Sphinx templates

I can't figure out how to get variables into Sphinx documents via a template. I am certainly making an elementary mistake, but while there is lots of documentation for using Jinja/Flask templates for web service and some documentation for Sphinx…
kcrisman
  • 4,374
  • 20
  • 41
23
votes
6 answers

Let sphinx use version from setup.py

If I do sphinx-quickstart I get asked about the version of the project. I want to avoid to have two places for the version of my project. How to do this in the python packing world?
guettli
  • 25,042
  • 81
  • 346
  • 663
23
votes
1 answer

Sphinx Autodoc and NumpyDoc

despite reading this tutorial, this question and the numpy docstring standard, I'm unable to get sphinx autodoc to play nicely with numpy docstrings. In my conf.py I have: extensions = ['sphinx.ext.autodoc', 'numpydoc'] and in my doc file I have: …
LondonRob
  • 73,083
  • 37
  • 144
  • 201
23
votes
4 answers

Substitutions inside links in reST / Sphinx

I am using Sphinx to document a webservice that will be deployed in different servers. The documentation is full of URL examples for the user to click and they should just work. My problem is that the host, port and deployment root will vary and the…
Martin Blech
  • 13,135
  • 6
  • 31
  • 35
22
votes
1 answer

sphinx customization of latexpdf output?

Just curious if anyone knows how to customize the sphinx output when using the latexpdf target? I've seen lots of custom stuff for html output, but cant seem to find any example of custom pdf output. Specifically, I'd be interested in customizing…
Brian
  • 229
  • 2
  • 3
22
votes
2 answers

Overriding Sphinx autodoc "Alias of" for import of private class?

I have a Python package that I am attempting to document with sphinx-autodoc. My python package has an __init__.py file that imports a class out from a submodule to make it accessible at the package level. from a.b.c.d import _Foo as Foo __all__ =…
Saff
  • 501
  • 3
  • 13
22
votes
1 answer

Automatically create a toctree for autodoc classes in Sphinx

I'm looking to increase the documentation in one of my libraries. I've been using sphinx to help build the documentation and recently started exploring the autodoc extension. It seems like in most professional documentation, each class documentation…
Ben Hoff
  • 1,058
  • 1
  • 11
  • 24
22
votes
3 answers

Include a text file *as is* in (Python) Sphinx Docs

(using Python-Sphinx Documentation tool) I have a .txt log file I'd like to build into _build/html unaltered. What do I need to alter in conf.py, index.rst, etc. Here is the layout: src/ index.rst some_doc.rst somefile.txt How do I get…
Gregg Lind
  • 20,690
  • 15
  • 67
  • 81
22
votes
1 answer

Conditional output in Sphinx Documentation

I'm writing some documentation with Sphinx and I'd like to print out a certain block of text only for HTML documentation, not for LaTeX documentation. Something tells me I should be able to do this with sphinx.ext.ifconfig but I can't figure out…
astrofrog
  • 32,883
  • 32
  • 90
  • 131
22
votes
2 answers

How to publish sphinx-generated documentation on bitbucket wiki automatically?

I have a python package with sphinx-generated documentation (using the automodules feature) and it can be made into a set of static html pages sitting in a _build directory in the git repository of the project. I would like to view this…
DrSAR
  • 1,522
  • 1
  • 15
  • 36
1 2 3
…
99 100