You don’t need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain. For example, the following defines a cross-reference to the mymethod method: :py:meth:`mymodule.MyClass.mymethod` Or even simpler (since the Python domain is the default): :meth:`mymodule.MyClass.mymethod` The documentation of TextWrapper.wrap that … Read more
Python 3.10 | (pipe, binary or) Union type hint syntax sugar Once you get access, this will be the way to go, it is sweet: def f(i: int|str) -> int|str: if type(i) is str: return int(i) + 1 else: return str(i) The PEP: https://peps.python.org/pep-0604/ Documented at: https://docs.python.org/3.11/library/typing.html#typing.Union Union type; Union[X, Y] is equivalent to X … Read more
All I wanted is to add ReST strikethrough in my sphinx doc. Here is how I did it: $ cd my-sphinx-dir $ mkdir -p theme/static $ touch theme/theme.conf $ touch theme/static/style.css In theme/theme.conf: [theme] inherit = default stylesheet = style.css pygments_style = pygments.css (this makes it look like the default theme (l. 2)) In theme/static/style.css: … Read more
It works if you add an __all__ list to the __init__.py files. For example: “””The __init__ docstr””” __all__ = [‘func1’, ‘func2’] from m1 import * from m2 import *
Here is an outline: Document your package using docstrings in the sources. Use sphinx-quickstart to create a Sphinx project. Run sphinx-apidoc to generate .rst sources set up for use with autodoc. More information here. Using this command with the -F flag also creates a complete Sphinx project. If your API changes a lot, you may … Read more
Installation: Install sphinx with pip for python3(pip3 like that). pip3 install -U sphinx Building: Makefile(linux/Mac) changes. SPHINXBUILD = python -msphinx In above line in Makefile change python to python3(or python3.x) like SPHINXBUILD = python3 -msphinx if default python is pointing to 2.x version python.
In general in restructured text use | Vertical bars | like this to keep line breaks
sphinx-apidoc only needs to be re-run when the module structure of your project changes. If adding, removing, and renaming modules is an uncommon occurrence for you, it may be easiest to just place the rst files under version control and update them by hand. Adding or removing a module only requires changing a few lines … Read more
The autosummary extension, with the autosummary_generate configuration variable set to True, can be used to 1) generate compact summary listings and 2) generate class documentation with one page per class. You have to explicitly specify each class to be included, but once this is done you have a setup for generating clear documentation where the … Read more
Since version 4.0 of Sphinx there is a new configuration option (autodoc_preserve_defaults). Setting autodoc_preserve_defaults = True in your conf.py will preserve the default values as they are in the source code.