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
0 answers

Sphinx documentation: custom images dir and _static directory for HTML docs

I am a relative beginner developing a Python package. At the root of the repository there are two important directories: images and docs. The former contains some png and svg files I would like to put inside a documentation, the latter is where I…
maciek
  • 1,807
  • 2
  • 18
  • 30
2
votes
2 answers

Trouble with custom footer in sphinx-rtd-theme

I'm having some issues adding a custom footer to my Sphinx .html files. I'm using the sphinx_rtd_theme. I've checked this post and tried it (and some of the suggestions in the comments) but to no avail. I'm not sure what I'm missing. Apologies if I…
als0052
  • 388
  • 3
  • 13
2
votes
1 answer

Documenting package __init__ imports with Sphinx

I have a Python package, felling which has a method: from felling.src.email import send_email Following from how Pandas handles imports such as pandas.DataFrame in felling.__init__.py I have: # felling.__init__.py from felling.src.email import…
this_josh
  • 333
  • 2
  • 11
2
votes
1 answer

Sphinx latex output filename

When running sphinx-build -b latex ... Sphinx writes a *.tex file into some output directory. The name of that *.tex file seems to somehow be derived from the project title set in conf.py. I'd like to integrate the Sphinx Latex generation into my…
levzettelin
  • 2,600
  • 19
  • 32
2
votes
2 answers

How do I unparse restructured text back into an rst file?

My question is a follow up to How to parse restructuredtext in python? where @mbdevpl provided code for parsing the file into a tree and doing some processing on the tree. I want to autoformat Python code in RST files. Now that I've discovered the…
Boris Verkhovskiy
  • 14,854
  • 11
  • 100
  • 103
2
votes
1 answer

What does ".. substitutions" mean in a rst file?

I have a README.rst file which I render with Sphinx. In that .rst file I see the following two lines at the end: .. substitutions .. |banner| image:: docs/source/logo/Banner.png I tried to find out what the phrase .. substitutions mean, but I did…
Alex
  • 41,580
  • 88
  • 260
  • 469
2
votes
1 answer

How to insert images after some specific functions in Sphinx docs?

I'm new to Sphinx. I generated .rst files using autodoc. The following is the .rst file for one of the modules: Building things ===================== Actions ---------------------------------- .. automodule:: acat.build.actions :members:…
Shaun Han
  • 2,676
  • 2
  • 9
  • 29
2
votes
1 answer

Is it possible to create docs for multiple packages within the same git repository with sphinx-apidoc?

I have a git repository which includes multiple packages which follow a namespace (i.e PEP 420. I am trying to create a ReadTheDocs documentation using Sphinx. The git repository looks like this repo:…
Shaked KO
  • 399
  • 2
  • 11
2
votes
1 answer

How to use Sphix's sphinx.ext.coverage's coverage_show_missing_items?

Sorry, I am a newbie trying to add Sphinx to auto-generate documentation for a Django project and also ensure sufficient documentation coverage of the project. I want to configure Sphinx to tell me which Objects are missing documentation by using…
Zhao Li
  • 4,936
  • 8
  • 33
  • 51
2
votes
2 answers

Sphinx generates HTML output from outdated source code

I'm using Sphinx to generate HTML documentation. Everything works great but for some reason, the source code and comments in the generated HTML file are really outdated. I don't even understand how it's possible. I've deleted all files multiple…
Arman Avetisyan
  • 349
  • 2
  • 10
2
votes
1 answer

ReadTheDocs and autodoc fail to find my package during build

I have been trying to build docs on readthedocs for my debut python package QutiePy. Building the docs works fine locally, but when I try to build on readthedocs, autodoc fails to populate my sections and gives the following warning: WARNING:…
franklinscudder
  • 111
  • 5
2
votes
1 answer

Rinohtype Sphinx restructured Text: Fixed Width Tables

Below is how we can get fixed-width, left-aligned tables in rst: .. list-table:: Table Caption :width: 100% :align: left But this doesn't seem to work in rinohtype. The alignment however i was able to get using my own stylesheet like…
Hamza Zubair
  • 1,232
  • 13
  • 21
2
votes
1 answer

Sphinx: create toc entries for each method

I am using sphinx-autodoc for documenting a class. I want the methods of the class to correspond to individual entries in the Sphinx TOC, so that they each spawn a link in the 'local TOC' sidebar. How can I achieve this? AFAICT, the autoclass…
polwel
  • 597
  • 5
  • 17
2
votes
1 answer

Unknown custom interpreted text role warning

In my Sphinx-doc instance, I have: at the end of my conf.py file: rst_prolog = """ .. role:: LaTeXLogo """ in some of my .rst files: :LaTeXLogo:`LaTeX` But this doesn't work since make html returns: WARNING: Unknown interpreted text role…
Denis Bitouzé
  • 520
  • 6
  • 18
2
votes
0 answers

When documenting with Sphinx, how do I insert [source] links manually

I'm using the sphinx.ext.viewcode extension to generate [source] links to classes and functions. This works great for documentation produced via autodoc, but there doesn't seem to be any restructured-text syntax available for me to make my own…
plc
  • 864
  • 8
  • 20
1 2 3
…
99 100