How to add extra whitespace between section header and a paragraph
You can use vertical bars at the beginning of lines to produce blank lines in the output. Like this: Heading ——- | | Paragraph with text.
python-sphinx
Can Sphinx napoleon document function returning multiple arguments?
Python only returns a single object. If you call serv,msg = foo(myinput) Then you are explicitly expanding the expression_list tuple which is generated when the function returns with this code return servers,msg You docstring should read some thing like this (with the Napoleon Google Style) “”” one line summary longer explanation Args: a (int): parameter … Read more
Retaining inline code inside references in Sphinx
If you have a look at :ref: documentation in its official web site about inline markups: :ref: To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation … I think (as @Kevin Horn) it’s no possible right … Read more
How to embed Plotly graphs in Sphinx documentation and nbsphinx
I can see two solutions to embed your notebook cells with plotly figures in a sphinx documentation. Convert the notebook to html using nbconvert or nbsphinx. Be sure to use the notebook renderer in order to include the plotly javascript bundle (maybe this was the reason why your figures did not display): see https://plot.ly/python/renderers/ for … Read more
Sphinx: force rebuild of html, including autodoc
It seems to work if the -E option is used along with -a. I added it to the html target in my Makefile and now changes in docstrings are picked up without updating any .rst files.
reStructuredText in Sphinx and Docstrings: single vs. double back-quotes or back-ticks difference
From the Sphinx documentation: The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role. As a matter of personal preference, when writing Python docstrings, I use interpreted text (single backquotes) … Read more
Markdown output for Sphinx based documentation [closed]
I didn’t find anything which could take reStructuredText files and convert them to Markdown except for Pandoc, so I wrote a custom writer for Docutils (the reference implementation of reStructuredText and what Sphinx is built upon). The code is available on GitHub. Note that it is only an initial implementation: it handles any reStructuredText document … Read more
Referencing figures with numbers in Sphinx and reStructuredText
In the latest versions of Sphinx (1.3+), numbering figures and referencing them from text got a bit easier as support for it is now built-in. In your text, you can do something like: .. _label: .. figure:: images/figure.* At :numref:`label` you can see… The end result should be something like “At Fig 1.1 you can … Read more
Sphinx, using automodule to find submodules
It sounds like you want to give the automodule directive a package name and have it recurse into the directory and document each Python module. That isn’t supported yet. You will ned to specify the full dotted module name for each module you want to document. For example, given the following directory structure (from the … Read more
Documenting class attributes with type annotations
I do not think you can put an Attribute section inside of your docstring to get your desired results. I tried giving each attribute a doc comment and specified the type and desired comment. class DataHolder: “”” Class to hold some data Each attribute needs its own doc comment with its type “”” #: bool: … Read more