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
80
votes
8 answers

How can I link/reference another reST file in the documentation?

I have simply no idea on how can I link to another document in the reST file. I want to link a file named install.rst to my quickstart guide in a paragraph. I don't know how can I achieve this. Please can you also refer to a great resource from…
Aditya ultra
  • 942
  • 1
  • 8
  • 15
77
votes
4 answers

Specifying targets for intersphinx links to numpy, scipy, and matplotlib

Following the documentation for setting up Sphinx documentation links between packages, I have added intersphinx_mapping = {'python': ('http://docs.python.org/2', None), 'numpy': ('http://docs.scipy.org/doc/numpy/', None), …
orome
  • 45,163
  • 57
  • 202
  • 418
75
votes
5 answers

Multi-line description of a parameter description in python docstring

So, reStructuredText is the recommended way for Python code documentation, if you try hard enough, you can find in the sphinx documentation how to normalize your function signature documentation. All given examples are single-line, but what if a…
Jocelyn delalande
  • 5,123
  • 3
  • 30
  • 34
69
votes
5 answers

How do we embed images in sphinx docs?

I am quite new in using sphinx, Doing documentation for the first time for the python project. How to embed image for example in the sphinx documentation ?
Ciasto piekarz
  • 7,853
  • 18
  • 101
  • 197
69
votes
2 answers

How to include a local table of contents into Sphinx doc?

How to include a local table of contents into Sphinx doc? I tried .. toc:: But that doesn't seem to have any effect: nothing is inserted in the document. Basically I need links to the sections in the current page to be placed at a certain…
Edy Bourne
  • 5,679
  • 13
  • 53
  • 101
66
votes
9 answers

How to preserve line breaks when generating python docs using sphinx

I am using Sphinx for generating docs for a python project. The output html is not preserving the line breaks which are present in the docstring. Example: Code def testMethod(arg1,arg2): """ This is a test method Arguments: arg1:…
Saurabh Saxena
  • 1,327
  • 2
  • 13
  • 26
63
votes
3 answers

Bold italic in ReStructuredText

I'm writing some documentation using ReStructuredText (ReST) format for the later web-page generation using Sphinx, and I cannot find a way to write some "bold italic" text. There are markers for the so-called 'emphasis' (italic) and 'strong…
v_2e
  • 2,603
  • 2
  • 22
  • 29
58
votes
7 answers

Are there any real alternatives to reStructuredText for Python documentation?

I'm starting an open source Python project shortly and I'm trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with autodoc, because I really like the idea of simply properly…
Hubro
  • 56,214
  • 69
  • 228
  • 381
57
votes
1 answer

Parsing reStructuredText into HTML

I'm making a framework in which I let developers describe their package using reStructuredText. I want to parse that reStructuredText into HTML so I can show it in a GUI. I'm familiar with the excellent Sphinx, but I've never otherwise parsed…
Ram Rachum
  • 84,019
  • 84
  • 236
  • 374
57
votes
1 answer

How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?

Sometimes a function in Python may accept an argument of a flexible type. Or it may return a value of a flexible type. Now I can't remember a good example of such a function right now, therefore I am demonstrating what such a function may look like…
Lone Learner
  • 18,088
  • 20
  • 102
  • 200
57
votes
10 answers

Modifying content width of the Sphinx theme 'Read the Docs'

I am using 'Read the Docs' Sphinx theme for my documentation. In the original theme, given below Read the Docs Sphinx Theme the content or main layout width is designed to be mobile friendly. However, for my project I would like this to be a bit…
hypersonics
  • 1,064
  • 2
  • 10
  • 23
56
votes
4 answers

Automatically Generating Documentation for All Python Package Contents

I'm trying to auto-generate basic documentation for my codebase using Sphinx. However, I'm having difficulty instructing Sphinx to recursively scan my files. I have a Python codebase with a folder structure like: └── src └──…
Cerin
  • 60,957
  • 96
  • 316
  • 522
56
votes
3 answers

How to make sphinx look for modules in virtualenv while building html?

I want to build html docs using a virtualenv instead of the native environment on my machine. I've entered the virtualenv but when I run make html I get errors saying the module can't be imported - I know the errors are due to the module being…
cerberos
  • 7,705
  • 5
  • 41
  • 43
54
votes
2 answers

How to do a link to a file in rst with sphinx?

I am writing a documentation and I would like to include links to pdf files or zip archives. How can I achieve that using rst language and sphinx ? If I do that here is a pdf file : `pdf `_ It does not work because, during the…
Ger
  • 9,076
  • 10
  • 37
  • 48
53
votes
7 answers

Include my markdown README into Sphinx

I would like to include my project's README.md into my Sphinx documentation like in Can sphinx link to documents that are not located in directories below the root document? - which is that in the resulting Sphinx html documentation I click on a…
Make42
  • 12,236
  • 24
  • 79
  • 155
1
2
3
…
99 100