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
35
votes
5 answers

Relative imports require the 'package' argument

I want to use Sphinx so it can automatically generate a pydoc for my python code but I'm getting an error. What an I doing wrong? conf.py sphinx config file import sys import os from django.conf import settings os.environ['DJANGO_SETTINGS_MODULE'] =…
ogward
  • 1,183
  • 4
  • 13
  • 18
34
votes
5 answers

How to right-align columns content in reStructuredText simple tables?

I'm editing the documentation for a project of mine using Sphinx, which in turn uses reStructuredText as markup language. I have a simple table (as opposed to grid table) in which the rightmost column reports contains numbers that I would like to…
mac
  • 42,153
  • 26
  • 121
  • 131
34
votes
4 answers

How to remove the cause of an unexpected indentation warning when generating code documentation?

The documentation code with the problem is at the beginning of a method: """ Gtk.EventBox::button-release-event signal handler. :param widget: The clicked widget (The Gtk.EventBox). :param event: Gdk.EventButton object with information regarding …
silviubogan
  • 3,343
  • 3
  • 31
  • 57
34
votes
8 answers

Sphinx, reStructuredText show/hide code snippets

I've been documenting a software package using Sphinx and reStructuredText. Within my documents, there are some long code snippets. I want to be able to have them hidden as default, with a little "Show/Hide" button that would expand them…
Adam Matan
  • 128,757
  • 147
  • 397
  • 562
34
votes
3 answers

How to show terminal/shell code snippets in Sphinx?

Using Sphinx, I know you can show a code snippet by having something like: .. code-block:: ruby. ${your ruby code goes here} How can I show a code snippet of terminal or shell commands not related to any languages? I don't care if they are not…
Shengjie
  • 12,336
  • 29
  • 98
  • 139
34
votes
1 answer

How to insert blank line using reStructuredText / Sphinx

I want to add a blankline (or add more whitespace) between heading and the image using ReStructuredText: ==== John ==== .. image:: _static/john.JPG :alt: John :height: 300px :width: 400px But I don't know how to do it?
xxks-kkk
  • 2,336
  • 3
  • 28
  • 48
33
votes
2 answers

Sphinx automodule: how to reference classes in same module?

I am trying to use the sphinx autodoc extension and specifically the automodule directive to automatically generate documentation for django app I am working on. The problem is that I want to create internal references to different classes within…
dino
  • 3,093
  • 4
  • 31
  • 50
33
votes
3 answers

Connect Sphinx autodoc-skip-member to my function

I want to use sphinx's autodoc-skip-member event to select a portion of the members on a certain python class for documentation. But it isn't clear from the sphinx docs, and I can't find any examples that illustrate: where do I put the code to…
bstpierre
  • 30,042
  • 15
  • 70
  • 103
33
votes
9 answers

Python Sphinx autodoc and decorated members

I am attempting to use Sphinx to document my Python class. I do so using autodoc: .. autoclass:: Bus :members: While it correctly fetches the docstrings for my methods, those that are decorated: @checkStale def open(self): """ …
Freddie Witherden
  • 2,369
  • 1
  • 26
  • 41
33
votes
2 answers

Remove package and module name from sphinx function

it's any way to remove the package and or module name from sphinx doc? Example: if exist a function called waa inside the module foo.bar, the rst code .. automodule:: foo.bar :members: will generate foo.bar.waa() and i want to output waa()
JuanBC
  • 333
  • 3
  • 6
33
votes
2 answers

How do I include the homepage in the Sphinx TOC?

Let’s say I’ve got a Sphinx project with the following sources: index.rst installation.rst templating/ index.rst module.rst fieldtype.rst index.rst (the homepage) has the following TOC tree: .. toctree:: :titlesonly: …
Brandon Kelly
  • 2,033
  • 2
  • 21
  • 38
33
votes
3 answers

Sphinx: how to exclude imports in automodule?

I have a Raspberry Pi project written in Python that uses RPi.GPIO module. All the work on the code is done on a Windows box where RPi.GPIO will not install and every time I try to run autodoc it crashes saying it cannot import…
pandasauce
  • 1,136
  • 2
  • 9
  • 11
33
votes
1 answer

Disabling individual Sphinx warning messages

I have many .rst files in my Sphinx tree which are intentionally excluded from any index tree. I get warnings like /filename.rst:: WARNING: document isn't included in any toctree How can I suppress specific warnings in Sphinx?
Mikko Ohtamaa
  • 82,057
  • 50
  • 264
  • 435
32
votes
2 answers

RESTful web service API documentation with Sphinx

What's the best way to markup methods/URLs for a RESTful webservice using ReST/Sphinx? Is there a default domain that's suitable for marking up URLs with their possible parameters, HTTP methods, headers and body content? Something along the lines…
deceze
  • 510,633
  • 85
  • 743
  • 889
32
votes
2 answers

How to host a privately owned documentation with ReadTheDocs or Sphinx

I am totally new to this thing. Spent a whole day trying to figure out the "most commonly used" approach. What I want to implement is something like readthedocs.org, but for a private customer (and proprietary project). Almost all of the FAQs, blog…
62mkv
  • 1,444
  • 1
  • 16
  • 28
1 2 3
…
99 100