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

Sphinx autosummary "toctree contains reference to nonexisting document" warnings

I am trying to automatically create api docs for a large python codebase using Sphinx. I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and…
user1287170
  • 713
  • 1
  • 6
  • 8
52
votes
4 answers

How to add custom css file to Sphinx?

How can I add a custom css file? The following config does not work: # conf.py html_static_path = ['_static'] html_theme = 'default' html_theme_options = { 'cssfiles': ['_static/style.css'] } Result: $ make html Running Sphinx v1.2.2 loading…
ole
  • 5,166
  • 5
  • 29
  • 57
51
votes
2 answers

How to show instance attributes in sphinx doc?

Is there any way to automatically show variables var1 and var2 and their init-values in sphinx documentation? class MyClass: """ Description for class """ def __init__(self, par1, par2): self.var1 = par1 * 2 …
Meloun
  • 13,601
  • 17
  • 64
  • 93
49
votes
1 answer

Sphinx docs: Remove blank pages from generated PDFs?

By default, Sphinx documentation outputs a PDF that's formatted for duplex printing. So there is a blank page between the title page and the TOC, the TOC and the introduction, the introduction and the first section, etc. My users are always going to…
AP257
  • 89,519
  • 86
  • 202
  • 261
49
votes
4 answers

How to include the toctree in the sidebar of each page

I'm generating html documentation in Sphinx. How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area…
Travis Bear
  • 13,039
  • 7
  • 42
  • 51
47
votes
1 answer

How should I document lists, optionals, and yields using Google-style Sphinx?

How do I indicate types for lists, optional arguments and return types for generators on Google-style docstrings using Sphinx-Napoleon? I've tried List[type] list of type Optional[type] type, optional and Yields: type: respectively; but all…
orome
  • 45,163
  • 57
  • 202
  • 418
47
votes
5 answers

How do I reference a documented Python function parameter using Sphinx markup?

I'd like to reference a previously-documented function parameter elsewhere in a Python docstring. Consider the following (admittedly completely artificial) example: def foo(bar): """Perform foo action :param bar: The bar parameter """ …
Inactivist
  • 9,997
  • 6
  • 29
  • 41
45
votes
3 answers

No generation of the module index "modindex" when using Sphinx

I have troubles creating a document directory (html) using sphinx-build. I tried sphinx-build -b html source build as well as make html but in both cases only the html-files search.html, index.html and genindex.html are generated. The file…
Karin
  • 451
  • 1
  • 4
  • 3
45
votes
1 answer

Fresh installation of sphinx-quickstart fails

Trying to get it going with Sphinx for the first time, with a clean Sphinx 1.1.3 installation, and shinx-quickstart fails. Should there be any dependencies installed? I tried to pip --force-reinstall sphinx but the result is the same. myhost:doc…
Anton Arhipov
  • 6,479
  • 1
  • 35
  • 43
44
votes
8 answers

The 'sphinx-build' command was not found.

This was our processes of installing Sphinx. > choco install python -y -f > pip install sphinx We know that sphinx installed because of the following output. > pip show sphinx --- Metadata-Version: 2.0 Name: Sphinx Version: 1.4.3 Summary: Python…
Shaun Luttin
  • 133,272
  • 81
  • 405
  • 467
44
votes
2 answers

Is Sphinx already suitable for C++ documentation?

I want to try out documentation generators for a new project in C++. I think my options are either Doxygen or Sphinx. Since I have projects in Python for which I'd like to use Sphinx, I wonder whether Sphinx is the right choice for C++ as well. The…
clstaudt
  • 21,436
  • 45
  • 156
  • 239
43
votes
3 answers

Has anyone used Sphinx to document a C++ project?

Sphinx is a new documentation tool for Python. It looks very nice. What I'm wondering is: How suitable this is for documenting a C++ project? Are there any tools for converting existing documentation (e.g. doxygen) to Sphinx format? Are there…
Nick
  • 27,566
  • 12
  • 60
  • 72
42
votes
2 answers

Which files should I tell my VCS to ignore when using Sphinx for documentation?

I want to start using Sphinx to document my project. I told Sphinx to use separate source and build directories during sphinx-quickstart. Now my directory layout is the following: MyProject/ myproject/ __init__.py mymodule.py …
gotgenes
  • 38,661
  • 28
  • 100
  • 128
42
votes
2 answers

Generating an external link in Sphinx

I'd like to link to some URL in my Sphinx docs: blah I have found something similar in the docs: http://sphinx-doc.org/ext/extlinks.html - but it is rather about replacing the custom syntax with the link, by…
Anton Arhipov
  • 6,479
  • 1
  • 35
  • 43
41
votes
2 answers

Python - How NOT to sort Sphinx output in alphabetical order

With Sphinx for Python how is it possible to avoid having all the method/function names sorted alphabetically in HTML? I want to keep them in the very same order as they are found in the source code.
Alex Poca
  • 2,406
  • 4
  • 25
  • 47
1 2
3
…
99 100