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

Skipping type hints in documentation

Let's consider the following function: def f(x: int, y: int) -> int: """Get sum of two integers. Parameters ---------- x : int first integer y : int second integer Returns ------- int sum of…
yarnabrina
  • 1,561
  • 1
  • 10
  • 30
2
votes
0 answers

How to create a named url for Django documentation created using Sphinx

In my Django project I created a rudimentary documentation using Sphinx. Now what I wanted to test was calling the documentation index page (index.html) as I would for a standard Django view using named url. I have been browsing for quite a while…
shaan
  • 351
  • 2
  • 15
2
votes
2 answers

autodoc duplicates class' methods

The automatically generated documentation duplicates the Methods for the Test class, as shown below. Why is this duplication occurring and how can it be stopped? I have tried several variations within the conf.py module, but it has been to no avail.…
sunspots
  • 1,047
  • 13
  • 29
2
votes
2 answers

GitHub sphinx-action can't find target Python modules and builds an empty sphinx doc

Tl;dr When I create a sphinx doc locally it builds as expected, but the GitHub Sphinx Build Action creates an empty doc. It must have to do with the sphinx-action not finding the target python modules as specified in conf.py. Any ideas to configure…
chamaoskurumi
  • 2,271
  • 2
  • 23
  • 30
2
votes
1 answer

sphinx + breathe + doxygen: .. doxygendefine:: only works for header files

I have a C project which I'm documenting with sphinx + breathe + doxygen. I want to document a define using .. doxygendefine:: MY_DEFINE This works fine, as long as MY_DEFINE is defined inside a .h file. When it is moved to a .c file, sphinx tells…
GNA
  • 479
  • 3
  • 18
2
votes
1 answer

Possible to define a target conditonally using `ifconfig` block (reStructuredText)

Is it possible to condtionally define a target in a reStructuredText file using ifconfig? I've set a variable in my sphinx conf.py file that I want to use to conditionally determine the URI of a target in my documentation: def setup(app): argv…
Michael Altfield
  • 2,083
  • 23
  • 39
2
votes
1 answer

Is there a standard format for documenting function-type parameters in Sphinx using sphinx.ext.napoleon?

I am using Sphinx to document one of my projects and one of the classes takes in a function as a parameter in its __init__. Is there a standard way to document this function-type parameter? I am also using sphinx.ext.napoleon to use Google…
Ben Soyka
  • 816
  • 10
  • 25
2
votes
0 answers

Using plot directive in Sphinx with testcode in docstring

Is there a way to incorporate the .. plot:: directive in Sphinx with the .. testcode:: one? When using doctest type I can integrate them like (just general idea): >>> import matplotlib.pyplot as plt >>> import numpy as np >>> x =…
001001
  • 530
  • 1
  • 4
  • 13
2
votes
1 answer

How to use auto-enumerator in nested lists (reStructuredText)

How do I make the following list in reStructuredText using the auto-enumerator character (#)? 1. one a. one_a b. one_b 2.two a. two_a I. one_a_i b. two_b In the above list, the first-level of the list is decimal, the second level is…
Michael Altfield
  • 2,083
  • 23
  • 39
2
votes
1 answer

How to Internationalize Sphinx (i18n)

From the defaults following an execution of sphinx-quickstart, how do I get language-specific directories like what's used by Read The Docs? I'm starting a new Sphinx documentation site that's hosted by GitHub Pages, built with GitHub Actions, and…
Michael Altfield
  • 2,083
  • 23
  • 39
2
votes
0 answers

reStructuredText with newlines on return statement

I'm getting a bit crazy on a problem which is fairly simple. I'm using Python with PyCharm and reStructuredText for docstring. Sometimes, my functions might return several values. I indent them with new lines but when seeing the docstring in PyCharm…
Ripitchip
  • 41
  • 6
2
votes
1 answer

Couldn't add relative path of README.md to Sphinx using recommonmark

As M2R is deprecated in Sphinx3. I tried to use recommonmark in order to include README.md to my documentation. I have the following structure project |--README.md |--docs |--|--conf.py |--|--index.rst |--|--... In conf.py I added recommonmark to…
J_yang
  • 2,672
  • 8
  • 32
  • 61
2
votes
2 answers

Sphinx autodoc gets stuck on random.choice() using mock

This is a continuation of a question I originally asked in this post: random.choice error due to np.linspace and np.logspace In this question, I have stripped down the problem to the bare minimum and was able to reproduce the problem where Sphinx is…
D_73
  • 55
  • 6
2
votes
1 answer

Basic syntax of comments and docstrings in Python code

I'm learning how to use Sphinx to create a documentation for my code. After I saw some examples like this: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the…
Henrique Oliveira Costa
  • 49
  • 1
  • 1
  • 5
2
votes
1 answer

Human readable iterables in Sphinx documentation

Sphinx-autodoc flattens dicts, lists, and tuples - making long ones barely readable. Pretty-print format isn't always desired either, as some nested containers are better kept flattened than columned. Is there a way to display iterables as typed in…
OverLordGoldDragon
  • 1
  • 9
  • 53
  • 101
1 2 3
…
99 100