Develop Reference

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 mod.submod.my_function(*args, **kwargs).
I would instead like Sphinx to just show the name of the function, i.e. the signature my_function(*args, **kwargs).
Do I have any way to drop the leading module and submodules in the signature?

Omitting module and package names preceding functions, methods and variables is done by setting the add_module_name configuration in your conf.py:
add_module_names = False
This is not obvious because of the numerous autodoc configurations that together with the sphinx-napoleon configurations make you expect the configuration elsewhere.

Yes, try this in docs/mod/submod.rst:
.. automodule:: mod.submod
.. autofunction:: my_function
See example HTML build and reST source in Pyramid documentation.
Bonus: see the Sphinx docs for 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.

Autosummary with toctree not creating documentation for methods

I'm using sphinx with the numpydoc extension and autosummary. After some experimentation, I added the following options to my conf.py file.
autosummary_generate = True
numpydoc_show_class_members = False
This is giving me a new file for each class referenced like below, and it also creates a summary table of all of the attributes and methods.
.. autosummary::
:toctree: generated/
:nosignatures:
MyClass
The problem is that while there is a summary table of the methods with the first line of the doc string, the names of the methods don't link to anything. How do I get the doc strings of the methods to also create files of their own (or at least generate the documentation in the same file as the class)?

First, make sure that in your conf.py file, the strings 'sphinx.ext.autodoc' and 'sphinx.ext.autosummary' are in the extensions list.
Second, you can either manually make the file with name mymodule.MyClass.rst inside the generate/ directory, which can be something like this:
mymodule.MyClass
================
.. currentmodule:: mymodule
.. autoclass:: MyClass
or, if you have a lot of classes, you can automate it using sphinx-autogen. You can run it from terminal (with cd same as the conf.py file) as :
sphinx-autogen *.rst

It appears that a template is needed to have sphinx generate rst files for the methods. Under _templates/autosummary I added a file named class.rst which looks like this and everything works.

Refer reST label in python docstring

I want to refer to reST label in my python method docstring and am expecting Sphinx to generate appropriate links.
I tried the following which does not work for me.
myown.rst
.. my-label:
Some explanation ...
mymodule.py
def somefunc():
""" See :ref:`my-label`. """
... rest of the code ...
This produces "See my-label" as text in the generated html file while I am expecting it to create appropriate hyper-link.
I see this kind of references in python-docs (e.g. see https://docs.python.org/3/library/functions.html#classmethod ) and reference to Function definitions (which is generic explanation). However, this is not generated from docstrings (as can be seen from funcobject.c) .. so I am inclined to think that it is handcrafted rst !!

Based on comment from #mzjn - the section header was missing in the rst file. Adding that and regenerating fixes the issue.

Sphinx: list of functions in a module

I have some python modules containing mostly functions and a few classes. Each one is documented using sphinx-autodoc in a separate rst. What I want to do is to create a table or list of the module's contents at the top of each page, so for example, of mymodule.py is
def first():
'First function'
def second():
'Second function'
And mymodule.rst is
Page Contents
-------------
:create_page_contents_list:
Members
-------
.. automodule:: mymodule
:members:
Then the output should look something like this:
Page Contents
-------------
first
second
Members
-------
first()
First function
second()
Second function
The question how to do :create_page_contents_list:. I've have a look at using a TOC, but it seems that I would need to manually create an entry for each item. I've also looked at autosummary, but I still need to list the members. Any suggestions for automating this? I'd rather avoid third-party extensions.

You probably want something like the autosummary extension. The actual autosummary extension will not quite do what you want, though.
An example of how you might extend autosummary to auto-detect the contents of the module is given in this answer

How do I document a module in Python?

That's it. If you want to document a function or a class, you put a string just after the definition. For instance:
def foo():
"""This function does nothing."""
pass
But what about a module? How can I document what a file.py does?

Add your docstring as the first statement in the module.
"""
Your module's verbose yet thorough docstring.
"""
import foo
# ...
For packages, you can add your docstring to __init__.py.

For the packages, you can document it in __init__.py.
For the modules, you can add a docstring simply in the module file.
All the information is here: http://www.python.org/dev/peps/pep-0257/

Here is an Example Google Style Python Docstrings on how module can be documented. Basically there is an information about a module, how to execute it and information about module level variables and list of ToDo items.
"""Example Google style docstrings.
This module demonstrates documentation as specified by the `Google
Python Style Guide`_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
module_level_variable1 = 12345
def my_function():
pass
...
...

You do it the exact same way. Put a string in as the first statement in the module.

It's easy, you just add a docstring at the top of the module.

For PyPI Packages:
If you add doc strings like this in your __init__.py file as seen below
"""
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
"""
# <IMPORT_DEPENDENCIES>
def setup():
"""Verify your Python and R dependencies."""
Then you will receive this in everyday usage of the help function.
help(<YOUR_PACKAGE>)
DESCRIPTION
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
FUNCTIONS
setup()
Verify your Python and R dependencies.
Note, that my help DESCRIPTION is triggered by having that first docstring at the very top of the file.