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 autodoc creates blank page on readthedocs, but correctly includes module docstring locally

I'm getting different results from autodoc when I run sphinx locally (versions 1.6.6 or 2.0.1 on Anaconda Python 3.6.8 for Mac) than when I run it on readthedocs.org (according to their log it's Sphinx version 1.8.5, and probably Python 2.7 since…
jez
  • 14,867
  • 5
  • 37
  • 64
2
votes
0 answers

Change the name of a module in Python Sphinx's autodoc

I am looking to autodoc some functions in a Python module using autofunction. Let's say, for example, the functions are defined in mylib/funcs/a.py and that file looks something like this: def myfunc(arg): """ My function does something """ …
Matt Dodge
  • 10,833
  • 7
  • 38
  • 58
2
votes
0 answers

Is there a way to create table from Python dictionary in Sphinx .rst file?

I have a dictionary in my python code which contains language codes and names: {'eng': English,'ger': German,....}. I have created variable in my sphinx conf.py file equivalent to this dictionary and I want to use that variable and show it in my…
Shushan Hovhannisyan
  • 21
  • 1
  • 4
2
votes
3 answers

Convert Python 3 to "simple" python that can be read by autodoc

I have a written a program in Python 3 and are using Sphinx to document it. Sphinx's autodoc is great, however it only works with Python 2. Some modules work fine in autodoc, however modules don't. Some examples: Python 2 complains about Python 3…
Giacomo
  • 412
  • 3
  • 10
2
votes
1 answer

Adding custom latex macros in mathjax_config

I am trying to add a new expectation operator macro for use in some docstrings. If in the math section I do: .. math:: \newcommand{\EE}[2][]{\mathbb{E}_{#1}\left[#2\right]} \EE{2+4} I get the correct output: If I instead try and…
luffe
  • 1,588
  • 3
  • 21
  • 32
2
votes
2 answers

Can I use Sphinx automodule but drop the module name in the signature?

I have a module mod with some submodule submod and use .. automodule:: mod.submod to generate documentation for it. The signatures of the elements (functions, classes etc.) in the modules now show the qualified name, like…
kuropan
  • 774
  • 7
  • 18
2
votes
1 answer

Setting up Sphinx Autodoc with existing project

I'm am completely new to Sphinx and have watched hours of tutorials, but could not find the answer to my issue I have a current project structure like the following -project folder |-sub folder 1 | |- sub folder 1.a | | - ... |-sub folder 2 …
Josh Sullivan
  • 107
  • 1
  • 11
2
votes
2 answers

Sphinx docs displaying locally but not at URL when pushed to GitHub

I generated Python docs using Sphinx using make html. When I opened index.html in my browser the docs displayed as expected and all links worked as expected. I then committed all docs and pushed to a branch in GitHub. When I access the url…
runnerpaul
  • 5,942
  • 8
  • 49
  • 118
2
votes
0 answers

How to fix long running command 'python setup.py test' in gitlab ci?

I'm trying to automate testing of my project using gitlab-ci/cd. Therefore I want to use the 'python setup.py test' command. But it's running about half an hour in the gitlab pipeline. On my local machine the preparation & tests are running…
ediordna
  • 300
  • 2
  • 15
2
votes
0 answers

Adding a new language support in base languages supported by Sphinx

I refer to the Internationalization documentation of Sphinx at http://www.sphinx-doc.org/en/master/usage/advanced/intl.html The base documentation need to be created in one of the supported languages at…
Ajay
  • 344
  • 3
  • 15
2
votes
2 answers

Sphinx starts chapter numbering from 0 in LaTeX output

I'm generating a PDF document With Sphinx using latex. ====================== RX-loader instructions ====================== Program ======= However this generates 0.1 RX-loader instructions 0.1.1 Program How do I make the numbering start with…
Kjeld Flarup
  • 1,471
  • 10
  • 15
2
votes
0 answers

How to navigate to a section tag # when opening a URL with Python's webbrowser?

When using Python's webbrowser.open(local_webpage_url#section) the #section tag at the end of the local_webpage_url gets ignored and the browser opens the HTML page but does not navigate to the section. (The address bar also does not show the…
Barus
  • 101
  • 14
2
votes
1 answer

Sphinx Docs | Can it support Algolia's Doc Search

I am wondering if anyone, knows if Algolia's DocSearch Free Service for Docs, can be integrated into a Sphinx Documentation Website. Thank you..
user10104341
2
votes
1 answer

Sphinx cannot include my JSON definition file due to json pointers

I'm documenting my JSON Schema using Sphinx to host it on ReadTheDocs. When I have my definitions in my main schema file all is well. But I want to move my definitions to an external json file. My code changes from "$ref":…
Paul Meems
  • 3,002
  • 4
  • 35
  • 66
2
votes
0 answers

How to get docstrings from decorated functions in Python with autodoc?

There is a officially known problem with sphinx autodoc that when your function is decorated, its docstring won't show up in the generated docs. From the autodoc home page: If you document decorated functions or methods, keep in mind that autodoc…
Alex Tereshenkov
  • 3,340
  • 8
  • 36
  • 61
1 2 3
…
99 100