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
1 answer

Sphinx-js can't find class documentation

I'm trying to setup sphinx_js but I keep receiving this error: ~/test_sphinx_js$ sphinx-build -b html docs/source/ docs/build/html/ Running Sphinx v4.4.0 building [mo]: targets for 0 po files that are out of date building [html]: targets for 1…
arnardo
  • 21
  • 2
2
votes
1 answer

Sphinx Documentation (autodoc) not working after uploading to Github

I have built sphinx documentation for my package. It is working fine when testing localhost. But after uploading it to Github and building docs on readthedocs.org the documentation page is not working which uses autodoc. Here is the link to the…
Spark Drago
  • 55
  • 6
2
votes
1 answer

Could not import extension sphinx_panels

While trying to use sphinx_panels in the rst (reStructuredText), I'm facing an error Could not import extension sphinx_panels. I've added the extension in the conf.py file as mentioned in the docs still facing the issue I even tried reinstalling but…
Alice Cooper
  • 43
  • 1
  • 6
2
votes
1 answer

Sphinx autosummary: dataclass inheritance

Following code makes Sphinx autosummary fail: @dataclasses.dataclass class Foo: bar: int class FooChild(Foo): pass My autosummary template (_templates/autosummary/class.rst): {{ name | escape | underline}} .. currentmodule:: {{ module…
ikamen
  • 3,175
  • 1
  • 25
  • 47
2
votes
0 answers

Use Cerberus Schemas to Automate Documentation

We are using cerberus extensively to validate json configuration files. We therefore have a wide range of schemas, which define how these json documents should be formatted. We would like to be able to use these schemas to auto-generate some…
OliverBurke
  • 51
  • 1
  • 5
2
votes
1 answer

Use module docstrings in Sphinx autodoc

In the Sphinx autodoc generated documentation I want kind of an introduction text for each module. I my logic this is related to the modules docstring. But Sphinx ignores it because it appears nowhere in the generated HTML files. # -*- coding: utf-8…
buhtz
  • 10,774
  • 18
  • 76
  • 149
2
votes
2 answers

Utilizing Sphinx with reStructuredText formatted docstrings

According to the writing docstrings tutorial of Sphinx, it is possible to utilize Sphinx's autodoc extension to automatically generate documentation. We can either write docstring with the Sphinx format, Google or Numpy (the latter two with the…
Cribber
  • 2,513
  • 2
  • 21
  • 60
2
votes
0 answers

Why does sphinx autosummary not create a toctree when used inside a class?

I am trying to use ..autosummary to document a module that replaces itself with a class upon import (lazy importing). Without lazy imports the module looks like this: """ The demp_project package The demp_project consists of the following…
FirefoxMetzger
  • 2,880
  • 1
  • 18
  • 32
2
votes
1 answer

Can sphinx auto generate a table of contents from all anchors on a page?

I'm trying to use the breathe plugin which is super limited out of the box: https://github.com/michaeljones/breathe It has this directive that generates a big dump of all classes/interfaces/etc and just puts them on the same page:…
red888
  • 27,709
  • 55
  • 204
  • 392
2
votes
0 answers

How to suppress warnings of hardcoded link reported by sphinx.ext.extlink extension?

After 4.4.0, Sphinx introduce a function for checking if hardcoded URLs can be replaced with extlinks, I got a lot of warning when build my documentation. I don't want to replace my links to extlink's role. How can I suppress them?
SilverRainZ
  • 156
  • 5
2
votes
2 answers

Specify build directory path for sphinx output?

Is it possible to redefine where sphinx outputs the build files? I want to run a local server (for testing purposes as the documentation is later hosted anyway) and implement some webhook APIs which obviously don't work if I don't have a responding…
glades
  • 3,778
  • 1
  • 12
  • 34
2
votes
1 answer

Include contents directive without changing headers to links

If I include a .. contents:: directive in a document all of the headings on the page become links to page anchors #id1, #id2... Without .. contents::, the headers on the page are not links (but do show the anchor link on hover). Is it possible to…
Andrew Deniszczyc
  • 3,298
  • 3
  • 19
  • 16
2
votes
1 answer

Link to a another Python file in the comments

I am trying to create a link to file2.py from file_1.py. For simplicity we can assume both are in the same package. What I would do in Java (via Intellij) is using {@link AnotherClass} but this is not possible in Python comment (or Pycharm): I also…
Yar
  • 7,020
  • 11
  • 49
  • 69
2
votes
0 answers

Creating docs for dispatched functions using Sphinx

I am using the multipledispatch package in order to dispatch some functions. I created meaningful docstrings for every function. The code just runs fine. # md.py from multipledispatch import dispatch @dispatch(int, int) def calc(a: int, b: int)…
Andi
  • 3,196
  • 2
  • 24
  • 44
2
votes
1 answer

gitlab-page for sphinx project is not working as expected

The link to the whole project https://gitlab.com/ComplicatedPhenomenon/doubancrawler I tested the generated document on local machine, it works fine and gitlab page is as below (https://complicatedphenomenon.gitlab.io/doubancrawler/api.html) Is…
ComplicatedPhenomenon
  • 4,055
  • 2
  • 18
  • 45
1 2 3
…
99 100