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
22
votes
2 answers

Sphinx autodoc gives WARNING: py:class reference target not found: type warning

I've got some code that uses a metaclass in python. But when sphinx autodoc is run it is giving the error: WARNING: py:class reference target not found: type The error is occuring in a line of an auto generated .rst file: .. automodule::…
Douglas Schneider
  • 221
  • 2
  • 4
22
votes
3 answers

Sphinx: List of supported languages for highlighting?

I'm using Sphinx for code documentation and use several languages within the code, I would like to setup highlighting for all of that code. Sphinx briefly mentions a few of the languages it supports (on this page), and then mentions that it uses…
Nic Foster
  • 2,864
  • 1
  • 27
  • 45
22
votes
5 answers

Image grid in reStructuredText / Sphinx

I'm using Sphinx to create documentation for a Python project I'm working on. I have three images I would like to display in a 1x3 grid (i.e. all on the same line), and I'm trying to figure out how to do this in reStructuredText. Right now I have ..…
jeremiahbuddha
  • 9,701
  • 5
  • 28
  • 34
21
votes
3 answers

define mark up for generic sphinx admonitions with a specific title

I am using Sphinx to generate HTML documentation for a Python program. I would like to use the generic admonition directive with a specific title and have it marked up in a way I can define, for example like content generated with the note…
equaeghe
  • 1,644
  • 18
  • 37
21
votes
2 answers

Github Pages with Sphinx generated documentation not displaying HTML correctly

I have been trying to publish a Sphinx generated documentation for our repository on Github pages with the theme provided by readthedocs.org. After a few attempts I managed to get it online by uploading the Sphinx generated HTML files in the…
Raf
  • 323
  • 2
  • 7
21
votes
4 answers

Automatically build Sphinx documentation when a source file changes

I'm using Sphinx to document one of my projects, and I like to preview my changes in my browser. I want to be able to save some changes to an .rst file, and be able to immediately refresh my browser and see the changes. Essentially I want to…
bradley.ayers
  • 37,165
  • 14
  • 93
  • 99
21
votes
5 answers

Working example of floating image in reStructured Text

I'm looking for the best way to have an image with text appearing beside it in reStructured Text. I have found several sites purporting to show how it's done but none show an actual functioning example. Several show what appear to be failing…
Ubuntourist
  • 775
  • 11
  • 26
21
votes
1 answer

How to correctly include other ReST-files in a sphinx-project?

My hand-written documentation/user-guide (written in ReStructuredText with sphinx) has become quite big so I started organize my .rst-files in sub-directories. In the index.rst I'm including a subindex.rst of each sub-directory which itselfs…
Patrick B.
  • 11,773
  • 8
  • 58
  • 101
21
votes
5 answers

Which Sphinx code-block language to use for JSON

I am using Sphinx to document a web service. I would like to show a formatted JSON web response using the code-block directive, which Spinx does via Pygments, but JSON doesn't have a syntax highlighter in Pygments. What language do you suggest I…
JayhawksFan93
  • 2,353
  • 3
  • 15
  • 11
21
votes
3 answers

How to turn warnings into errors when building sphinx documentation with setuptools?

I am using setuptools to build my sphinx documentation of a python project (python setup.py build_sphinx). As found on, e.g., this site, I have configured the build process using the setup.cfg: [build_sphinx] source-dir = docs/source build-dir =…
Thomas
  • 1,277
  • 1
  • 12
  • 20
21
votes
5 answers

Internal hyperlink in reStructuredText with customized text

I know how to create an external hyperlink with customized text. `My cool link `_ But I want to link to an internal reference. .. _foo: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt…
John
  • 935
  • 6
  • 17
21
votes
2 answers

How can i include the `genindex` in a Sphinx TOC?

Sphinx generates an index named genindex when building a documentation and therefore forbids to use that name for a document. Now, how would I include a link to that index in a table of contents? I've tried this: .. toctree:: :maxdepth: 2 …
funky-future
  • 3,716
  • 1
  • 30
  • 43
21
votes
2 answers

Can't use :ref: with a Label using Sphinx doc

I have a problem with using Sphinx-doc's :ref: role, I put a label above a paragraph and then I try to link to that label from another doc but inside the same project. The label I use in one document: .. _hal_1k_1p: And the ref I try to use to link…
Raiu
  • 315
  • 1
  • 2
  • 6
21
votes
1 answer

Make Read the Docs include autodoc documentation for special-members?

I have a module with two documented global special-members. Running Sphinx locally creates documentation that includes their docs, but Read the Docs doesn't. It uses the built-in type's documentation instead. I have tried both styles: #: and…
Márcio
  • 677
  • 8
  • 15
21
votes
1 answer

Sphinx apidoc - don't print full path to packages and modules

I am quite new to sphinx and I am trying to use it as API reference for my project. Maybe after that as project documentation too. I generate it using these two commands sphinx-apidoc -e -o doc/api tracer sphinx-build -b dirhtml doc/…
FrostyX
  • 358
  • 3
  • 10
1 2 3
…
99 100