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
26
votes
3 answers

What is the Mathworks way to generate Matlab HTML documentation?

I am working on shared Matlab code and we would like to share a generated documentation as searchable HTML documents within our local network. I know of the following methods to generate a documentation: Write a converter to C++-like files. This is…
Lukas
  • 2,330
  • 2
  • 22
  • 31
26
votes
4 answers

What does "Title level inconsistent" mean?

I've been getting warnings in my documentation builds of the variety "Title level inconsistent". As far as I can tell, I have a consistent structure that looks something like: Big Title ========= Section ------- Subsection ~~~~~~~~~~ but the…
keflavich
  • 18,278
  • 20
  • 86
  • 118
26
votes
1 answer

Cannot Get TOCTREE in Sphinx to Show Link

I am new to Sphinx. I tried out the tutorial but I failed to generate the link in the contents. The error that I got C:\Users\mhaikalm\sphinxtest\source\index.rst:11: WARNING: toctree contains refe rence to document 'intro' that doesn't have a…
Haikal Nashuha
  • 2,958
  • 7
  • 44
  • 67
25
votes
1 answer

Read-the-docs build fails with "cannot import name 'PackageFinder' from 'pip._internal.index'"

The build of Sphinx docs on read-the-docs fails with the following error (complete log below): ImportError: cannot import name 'PackageFinder' from 'pip._internal.index'…
Bruno Rijsman
  • 3,715
  • 4
  • 31
  • 61
25
votes
3 answers

How to add Sphinx-generated index to the sidebar when using Read the Docs theme?

I'd like to have a link to the automatically generated index in the sidebar when using sphinx-rtd-theme. I've tried adding it to the toctree: .. toctree:: first second Index <:ref:`genindex`> but this resulted in WARNING: toctree…
VZ.
  • 21,740
  • 3
  • 39
  • 42
25
votes
5 answers

Include specific special-methods in sphinx

I have a bunch of classes which use "special-methods": class Foo(object): "Foo docstring" attr1 = "Attribute!" #: first attribute attr2 = "Another Attribute!" #: second attribute def __init__(self): self.x = 12 def…
mgilson
  • 300,191
  • 65
  • 633
  • 696
25
votes
1 answer

Using sphinx to auto-document a python class, module

I have installed Sphinx in order to document some Python modules and class I'm working on. While the markup language looks very nice, I haven't managed to auto-document a Python code. Basically, I have the following Python module: SegLib.py And A…
Adam Matan
  • 128,757
  • 147
  • 397
  • 562
25
votes
1 answer

Using Sphinx-apidoc to generate documentation from C++ code

There have been a couple of threads on this topic in the past that claim Sphinx doesn't support this at all. I had my doubts but either it has been updated since or the documentation for it was quite well hidden, because here is a link on the…
user1488804
  • 840
  • 1
  • 13
  • 27
24
votes
3 answers

How to document Python function parameters with Sphinx?

I'm trying to clean up my python code documentation, and decided to use sphinx-doc because it looks good. I like how I can reference other classes and methods with tags like: :class:`mymodule.MyClass` About my…
Adam Morris
  • 8,265
  • 12
  • 45
  • 68
24
votes
2 answers

In Python sphinx, how to link to a file in _static directory

I have some code and data samples I copy to _static directory and I would like to link to those files in documentation, something like: .. _pca-run.py: _static/example.data But the problem is that sphinx does not create a proper relative link to…
Mitar
  • 6,756
  • 5
  • 54
  • 86
24
votes
2 answers

Python and sphinx: bullet point list in multiline google style docstring

I am currently documenting my Python project using Sphinx. I have come across an issue when including a bullet point list in the multi-line part of a docstring. I would like to include a bulleted list, but one of the items is quite long. I would…
Pierre Massé
  • 693
  • 1
  • 5
  • 23
24
votes
2 answers

In reStructuredText, how to put an inline literal inside of a hyperlink?

In my reStructuredText document, I have a section defined like so: Update the ``PATH`` Environment Variable ---------------------------------------- I would like to link to this section like so: * `Update the ``PATH`` Environment Variable`_ But,…
davidrmcharles
  • 1,923
  • 2
  • 20
  • 33
24
votes
3 answers

A literal "*" in RestructuredText

I am looking at this snippet of code: def ook(*args): """Some silly function. :param *args: Optional arguments. """ ... And as soon as I run Sphinx, I get the oh-so helpful error: WARNING: Inline literal start-string without…
Sardathrion - against SE abuse
  • 17,269
  • 27
  • 101
  • 156
24
votes
4 answers

External Relative Link in Sphinx toctree directive

I'm using Sphinx to build my documentation. I'm using other tool for API reference. I have my docs in a directory and the API reference in directory name api inside of it. I want to have a link from the documentation to the API reference. I'm able…
Ido Ran
  • 10,584
  • 17
  • 80
  • 143
24
votes
1 answer

How can I generate documentation for a Python property setter using Sphinx?

I have a Python class something like the following, with docstrings intended to be converted into documentation by Sphinx: class Direction(object): """ A direction in which movement can be made. """ def __init__(self): …
Matthew Murdoch
  • 30,874
  • 30
  • 96
  • 127
1 2 3
…
99 100