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

Make the heading levels of documents automatically dependent of the depth's levels of the (sub(sub(...)))folders they belong to

Suppose I have: a foo0.rst file at the root (source) of my sphinx-doc source folder, a foo1.rst file in a subfolder subfolder1 of source, a foo2.rst file in a subfolder subfolder2 of subfolder1, that is: $ tree source source ├── foo0.rst └──…
Denis Bitouzé
  • 520
  • 6
  • 18
2
votes
1 answer

Capturing Graphviz figures in sphinx-gallery

I'm generating examples with sphinx-gallery, and would like to embed graphviz outputs automatically, similar to how matplotlib figures are captured. A screenshot of my current progress is below. Notice the captured Out shows string or byte…
Alexander L. Hayes
  • 3,892
  • 4
  • 13
  • 34
2
votes
2 answers

Create Sphinx autodoc for a package loading pywin32 on Linux

I wrote a package that uses pywin32 to sync GitLab issues with Microsoft Projects. I would like to use readthedocs to host the documentation. The problem is that I can't install pywin32 as a Linux environment is used there. Any suggestion on how to…
Kound
  • 1,835
  • 1
  • 17
  • 30
2
votes
0 answers

Multiple netlify static sites served under a single cloudfront domain path

I have multiple netlify static sites that I want to serve in their entirety under a path of a cloudfront domain. However, resources that don't reside at the root of the netlify app are not being served (raise a…
benjhastings
  • 21
  • 2
2
votes
0 answers

Why is sphinx autodoc failing to generate links to some function parameter types?

I've got sphinx autodoc working with sphinx-autodoc-typehints and intersphinx such that :class: references render links when used in docstrings. Function parameter types also render type links for std library types. My problem is that my custom…
Tyler Gannon
  • 872
  • 6
  • 19
2
votes
1 answer

Should you commit environment.pickle when working with Sphinx?

I'm using Sphinx to generate some documentation, and I publish this built documentation in a git repository. One of the files in the build directory is called environment.pickle and seems to be in binary format, i.e. not plaintext. What is this…
Newbyte
  • 2,421
  • 5
  • 22
  • 45
2
votes
0 answers

Why does sphinx-build (installed with Python 3.8.6) use Python 3.8.2?

When doing imports in conf.py, I got complaints from autodoc when running sphinx-build source/ build/: WARNING: autodoc: failed to import module '' from module ''; the following exception was raised: No module named…
mrclng
  • 483
  • 2
  • 14
2
votes
0 answers

Convert codesnippet to HTML code in Sphinx?

I am pretty new to Sphinx and HTML, CSS, etc.., in general. In this example the following code: .. toggle-header:: :header: Example 1 **Show/Hide Code** Content for header Generates this HTML code:
…
Situ
  • 21
  • 4
2
votes
1 answer

What requirements are there for cross-referencing a Python object in Sphinx?

I'm using :class: and getting a lot of warnings WARNING: py:class reference target not found: mypkg.submodule.class. I can't find anywhere in the documentation what exactly the requirements are for a correct cross-reference. This is currently an…
Robin De Schepper
  • 4,942
  • 4
  • 35
  • 56
2
votes
0 answers

C++ Visibility macro breaking documentation Sphinx/Doxygen formatting

I have this problem where I added a macro to set the visibility of certain functions to my code like this: #define PUBLIC_API __attribute__((visibility("default"))) The problem is that it seems to have broken the formatting when displaying the…
catflaps
  • 135
  • 1
  • 3
2
votes
0 answers

Automatically link functions/classes in code example in Sphinx documentation

I am building code documentation with Sphinx. Let's say at some point there is documentation for a class foobar.Foo, i.e. something like .. autoclass:: foobar.Foo :members: At some other place, I have a code example (included using…
luator
  • 4,769
  • 3
  • 30
  • 51
2
votes
1 answer

Prevent term ending in an underscore from appearing as hyperlink in Sphinx docs

I have a class method with an argument that ends in an underscore, from_, and I am using autoclass to generate the documentation for the class. I want the argument from_ to appear as normal text in my Sphinx documentation, but currently it appears…
SlowLoris
  • 995
  • 6
  • 28
2
votes
0 answers

How to Use `m2r_parse_relative_links` in m2r2?

I have an image in my README.md that I would like to be displayed in my sphinx docs (/docs/readme.rst). Can someone show me how to use m2r_parse_relative_links to make this work? The m2r documentation does not include any information on how to use…
adam.hendry
  • 4,458
  • 5
  • 24
  • 51
2
votes
1 answer

How do I make my sphinx directive add assets to _static folder?

I'm building a custom sphinx extension and Directive to render interactive charts on sphinx and ReadTheDocs. The actual data for a chart resides in a .json file. In a .rst document, including a chart looks like this: .. chart:: charts/test.json …
thclark
  • 4,784
  • 3
  • 39
  • 65
2
votes
2 answers

Python-sphinx: documentation of a child class won't show when "autodoc_mock_imports" is enabled

Question Is there a way to generate sphinx documentation of a child class without installing the library containing its parent class on GitLab CI (or any comparable CI tool)? Edit: I have 7 such classes and ca. 10 member functions per class on…
Bill Huang
  • 4,491
  • 2
  • 13
  • 31
1 2 3
…
99 100