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

In Sphinx documentation, is it possible to use the module name to specify a code sample to be included?

I'd like to include a code example in my sphinx documentation. I don't, however, want to refer to the file by its path, but would rather specify it by its module name. That is, instead of doing it the way indicated here Showing code examples ..…
Ed L
  • 1,947
  • 2
  • 17
  • 30
2
votes
0 answers

Does Sphinx natively support documentation on side-effects?

Other documentation tools support specific tags in order to document side-effects (such as the @modifies tag in JSDoc, for example). I was wondering if Sphinx or any plugin may offer something similar, as I could not find anything so far.
hblanco
  • 116
  • 7
2
votes
1 answer

How to customize the code-block language of Sphinx?

Consider the below situation: .. code-block:: my_lang ... If I want to make my_lang as some stuff such as Python, how can I do it?
Carson
  • 6,105
  • 2
  • 37
  • 45
2
votes
1 answer

Difficulties documenting enum classes?

I'm trying to document a module I'm maintaining, and I'm finding it very difficult to get my enum classes documented properly. For instance, here's one that I'd like to document properly (source): class QOSLevel(Enum): '''Quality of service…
alexgolec
  • 26,898
  • 33
  • 107
  • 159
2
votes
1 answer

Extracting a C++ code snippet in a sphinx document

I am trying to extract a specific code snippet (a test) from my sources to output it in the documentation. TEST_CASE("std::vector") { //! [MyTest] std::vector v = {42,43}; CHECK( v.size() == 2 ); //! [MyTest] } In doxygen, I can refer to…
Bérenger
  • 2,678
  • 2
  • 21
  • 42
2
votes
2 answers

Add a warning directive at the top of every page on a Sphinx RTD site

I'd like to add a simple warning directive at the top of every page on a Sphinx RTD site: .. attention:: The next major release of this project will launch on X date. In the meantime, we're looking for feedback. If you'd like an early…
Abe
  • 22,738
  • 26
  • 82
  • 111
2
votes
0 answers

Sphinx link to python standard library documentation

In order to be able to reference standard python documentation I have added to my config file the following: import os import sys sys.path.insert(0, 'C:/ProgramData/Anaconda3/lib/site-packages') sys.path.insert(0,…
Diego F Medina
  • 429
  • 3
  • 14
2
votes
1 answer

sphinx documentation exclude a baseclass from :inherited-members:

I'm documenting some Python code that has multiple layers of inheritance using Sphinx. The structure is roughly: class _foo(np.ndarray): #do _foo stuff class bar(_foo): #do bar stuff class baz(_foo): #do baz stuff With…
defladamouse
  • 567
  • 2
  • 13
2
votes
3 answers

Python: Sphinx namedtuple documentation

I'm trying to document namedtuple. When I build the docs I get a warning WARNING: duplicate object description and same empty functions after documented ones. For example: How to delete those aliases? I've already tried this solution, writing few…
Artem
  • 563
  • 3
  • 17
2
votes
1 answer

Sphinx field list - url line break formatting

I'm using sphinx to generate the documentation for a project. I'm using field list, referencing a long url. My reST script is below: **Operação** ^^^^^^^^^^^^ :Fonte: https://google.com.br :Github:…
Rafael Higa
  • 655
  • 1
  • 8
  • 17
2
votes
1 answer

How do I display an image in Sphinx docs from a Python docstring?

Python Docstring Image Embed In a Python docstring I have a reStructuredText directive to display an image: .. image:: ./images/code_quality.png Instead of the image, I get a small icon and a path: _images/code_quality.png Screen clip of link…
jhachtel
  • 43
  • 9
2
votes
0 answers

Python Sphinx documenting through directories

I'm having to use Sphinx to document a whole project folder, with lots of subfolders and python scripts inside them. What's the best solution to automate this process? The project will be constantly updated, and the documentation should be properly…
Rafael Higa
  • 655
  • 1
  • 8
  • 17
2
votes
1 answer

How to make translations of full articles from po files in Sphinx or gettext

I'm writing a project documentation in Sphinx. I want to make translations of my .rst files, and I generated and translated .po files. Sphinx generates html translations fine, but I want to have .rst or markdown full articles (to use them on another…
Yaroslav Nikitenko
  • 1,695
  • 2
  • 23
  • 31
2
votes
3 answers

sphinx-build command not found in gitlab ci pipeline / python 3 alpine image

I want to specify a GitLab job that creates a sphinx html documentation. I am using a Python 3 alpine image (cannot specify which exactly). the build stage within my .gitlab-ci.yml looks like this: pages: stage: build tags: - buildtag …
bk_
  • 751
  • 1
  • 8
  • 27
2
votes
1 answer

Is there a method for displaying plots after plt.show() with sphinx or keep scope after .. plot::

I am using sphinx with numpydocs, doctest, and the scipy theme. When using .. plot:: in a docstring, the plots are all created, except instead of showing where they are called, they all move to the end of the documentation. Is there a way to force…
001001
  • 530
  • 1
  • 4
  • 13
1 2 3
…
99 100