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
21
votes
6 answers

Sphinx inline code highlight

I use Sphinx to make a website that contains code samples. I'm successful using the .. code-block directive to get syntax highlighting. But I can't get inline syntax highlighting using this code: .. role:: bash(code) :language: bash Test inline:…
user378147
21
votes
6 answers

Sphinx documentation inside a Flask running web application

I've locally built static Sphinx documentations (using make html). I wish now to integrate the Sphinx files into my webapp that runs with Flask. From the Flask running application, I simply mean to include an hyperlink towards the Sphinx…
mannaia
  • 860
  • 2
  • 11
  • 27
20
votes
2 answers

Embed external html file using iframe in Sphinx

I'm trying to embed an interactive graph, which is saved as an html file, in a reStructuredText document using iframe: .. raw:: html The html file is in the same directory as my…
shrgm
  • 1,315
  • 1
  • 10
  • 20
20
votes
3 answers

Customize templates for `sphinx-apidoc`

I've recently tried using sphinx-apidoc from Sphinx to help generate Sphinx specific reStructuredText from the API of a Python project. However, the result I'm getting is: Anyone know if I can customize the template sphinx-api uses for its output?…
estan
  • 1,444
  • 2
  • 18
  • 29
20
votes
1 answer

Restructured text (rst) http links underscore ('__' vs '_' use)

With restructured text, I've seen both these used: `Some Link `_ `Some Link `__ Both generate the same output from Sphinx, Whats the difference between using _ or a double underscore __ for http URL…
ideasman42
  • 42,413
  • 44
  • 197
  • 320
20
votes
4 answers

How do I document classes imported from other modules - hence without the declaration module's name?

The package I am documenting consists of a set of *.py files, most containing one class with a couple of files being genuine modules with functions defined. I do not need to expose the fact that each class is in a module so I have added suitable…
Major Eccles
  • 491
  • 3
  • 8
20
votes
3 answers

How do I output a config value in a Sphinx .rst file?

I've got the following in conf.py: def setup(app): app.add_config_value('base_url','http://localhost:2000', True) How do I get this into my .rst files? I wrote this: :base_url:/my_app/api/application/ But it only prints :base_url: instead of…
Matt Culbreth
  • 2,835
  • 2
  • 19
  • 17
19
votes
3 answers

How to add a logo to my readthedocs - logo rendering at 0px wide

This happens locally via sphinx running readthedocs theme, it also happens in readthedocs.io. I have added an svg logo (actually it's just the downloaded rtd logo.svg copied from their site for testing). I've added the settings to conf.py and html…
Joel Marks
  • 211
  • 2
  • 3
19
votes
3 answers

Can I render HTML on GitLab?

GitLab doesn't render HTML for me, but just display the source code: Background: I used sphinx to generate the HTML and tried to show the doc at GitLab. I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in…
YJZ
  • 3,934
  • 11
  • 43
  • 67
19
votes
3 answers

What is the difference between var, cvar and ivar in python's sphinx?

I was reading through the sphinx documentation pages and ironically found that the documentation on the difference between var, ivar, and cvar very lacking. I was wondering if someone could explain the difference between each of the different name…
Rusty Weber
  • 1,541
  • 1
  • 19
  • 32
19
votes
3 answers

Sphinx and re-usable Django apps

Problem While trying to generate sphinx documentation for a re-usable Django application I struck upon the following snafoo. When sphinx parses the model.py code it is thwarted by the code therein trying to access the Django project settings. As…
Carel
  • 3,289
  • 2
  • 27
  • 44
19
votes
2 answers

How to make Sphinx show Python 3 typing type hints next to the argument description instead of on the function signature?

I am generating a HTML documentation of a Python 3 module automatically from its reStructuredText docstrings of its functions by using Sphinx (make HTML). The generated HTML documentation looks fine so far, but the parameter types of the function…
Johann Hagerer
  • 1,048
  • 2
  • 10
  • 28
19
votes
1 answer

How to include PDF in Sphinx documentation?

I have a PDF that has some in depth explanation for an example in the Sphinx documentation for a package I have. Is there a way to easily include the PDF in my project (and have it copy over when I build the docs)? I tried linking to it with :doc:…
John Salvatier
  • 3,077
  • 4
  • 26
  • 31
19
votes
1 answer

Sphinx: Resume list numbering after a note section

Consider the following list in ReStructuredText: Broken list example ------------------- #. First do spam #. Then do ``eggs`` .. note:: Nobody expects the Spanish Inquisistion #. The list restarts after the note When the list is compiled…
Adam Matan
  • 128,757
  • 147
  • 397
  • 562
19
votes
3 answers

Python Sphinx Autosummary: Automated listing of member functions

How can I tell the autosummary extension not to only list a single class but also all the class' members? If I use: .. autosummary:: MyClass In the resulting html file, there will only be one short summary like: MyClass(var1, var2,....) My…
SmCaterpillar
  • 6,683
  • 7
  • 42
  • 70
1 2 3
…
99 100