Here are three alternatives: To ensure that __init__() is always documented, you can use autodoc-skip-member in conf.py. Like this: def skip(app, what, name, obj, would_skip, options): if name == “__init__”: return False return would_skip def setup(app): app.connect(“autodoc-skip-member”, skip) This explicitly defines __init__ not to be skipped (which it is by default). This configuration is specified … Read more
The solution that works for Sphinx is to prefix the reference with ~. Per the Sphinx documentation on Cross-referencing Syntax, If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text. So … Read more
After finding this question I settled on the following, which is valid Sphinx and works fairly well: def some_function(first, second=”two”, **kwargs): r”””Fetches and returns this thing :param first: The first parameter :type first: “int“ :param second: The second parameter :type second: “str“ :param \**kwargs: See below :Keyword Arguments: * *extra* (“list“) — Extra stuff * … Read more
Autodoc can’t find your modules, because they are not in sys.path. You have to include the path to your modules in in the sys.path in your conf.py. Look at the top of your conf.py (just after the import of sys), there is a sys.path.insert() statement, which you can adapt. By the way: you can use … Read more
The expression “reST/Sphinx” makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I’m going to cover both since people using RST are likely to run into both cases at some point: Sphinx Besides the domain-specific directives … Read more
You can check this script that I’ve made. I think it can help you. This script parses a directory tree looking for python modules and packages and creates ReST files appropriately to create code documentation with Sphinx. It also creates a modules index. UPDATE This script is now part of Sphinx 1.1 as apidoc.
You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented in the Sphinx documentation. Install myst-parser (pip install myst-parser) and then edit conf.py: # simply add the extension to your list of extensions extensions = [‘myst_parser’] source_suffix = [‘.rst’, ‘.md’] I’ve created a small example project on … Read more