Develop Reference

Python sphinx documentation -- autosummary links not consistent using autodocsumm extension

I am generating documentation for a Python project using the Sphinx autodocsumm extension with the following autosummary configuration to show a summary of only classes at the beginning of the document.
Module1 module
----------------------------
.. automodule:: src.Module1
:members:
:undoc-members:
:show-inheritance:
:autosummary:
:autosummary-no-nesting:
In the generated html, the summary class name hyperlinks are not consistent -- one is a path to a separate summary stub file, while the other just references an anchor in the main src.html file.
file:///project_path/docs/_build/html/src.Module1/src.Module1.Class1.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2
I can't figure out why the classes are being treated differently during the make. The first one is a large class with many members while the second is a small class with just a few lines, so maybe there is some threshold for generating the stub file? My preference is to not reference a separate file and only jump to the respective anchor within the main document for all summary links.
Is there a setting to control this behavior?
Edit: Upon further review, I don't think this has anything to do with autodocsumm after all. I notice after doing the "make html" a subfolder is create only for the Class1 documentation while Class2 is referenced only in the main src.html file.
project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html
So... Why are these two classes treated differently? Also, is there any setting to prevent a separate folder and html file from being generated?

I finally figured out the issue... While narrowing my project down to a minimum reproducible example, I noticed an src.Module1 folder under docs that had rst files for Class1 only.
Project
docs
_build
src.Module1
Module1.Class1.rst
src.Module1.Class1.rst
I'm not sure what I did to produced that folder, but after deleting it and rebuilding the Sphinx html, I am now getting the document anchors I expect directly in the src.html file:
file:///project_path/docs/_build/html/src.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2

Need a different module name when using Python's Sphinx automodule directive

I have a file layout that looks like:
/my_module
__init__.py
submodule1.py
submodule2.py
I use Sphinx's automodule directive like:
.. automodule:: my_module.submodule1
It produces documents that say my command name is something like: my_module.submodule1.my_function. But my __init__ pulls submodule1 into the my_module namespace. So what I really want is for the documentation to say my_module.my_function instead. Leave out the submodule1, since that's not what users are going to use.
Is there a way to do this?

Not exactly, but you can get close. There is the ~ (tilde) in standard 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. This does not work with all cross-reference roles, but is domain specific.
You might be able to use substitutions or the raw directive, but that would bypass the advantage of using autodoc and its directives.

Using Sphinx to automatically generate a separate document for each function

I've been building a Python module with many different functions.
I'm using Sphinx and readthedocs to provide documentation. I've made decent progress, but currently I have one massive page that gives the documentation for all of my functions (in alphabetical order).
I've looked at other projects which have a separate page for each function. In looking through their source, I find a separate .rst file has been created for each. I assume this is done automatically, and this page on generating autodoc summaries seems like it's describing some of this, but I just can't make sense of it.
sphinx-apidoc has an option (-e) to create a page for each module, but I want one for each function.
How does one use Sphinx to automatically generate a separate page for each function?
additional information
To add info for one of the answers below, I've put the following into my EoN.rst file, which sits in the subdirectory docs.
EON documentation
=================
.. automodule:: ../EoN
:members:
.. currentmodule:: ../EoN
.. autosummary::
:toctree: functions
fast_SIR
fast_SIS
I get the error message
$ sphinx-autogen -o docs/generated docs/*.rst
[autosummary] generating autosummary for: docs/index.rst, docs/methods.rst, docs/quickstart.rst
[autosummary] writing to docs/generated
WARNING: [autosummary] failed to import u'fast_SIR': no module named fast_SIR
WARNING: [autosummary] failed to import u'fast_SIS': no module named fast_SIS
fast_SIS and fast_SIR sit within ../EoN.py

I think the sphinx-automodapi Sphinx extension may do what you need. Essentially to document a module you would just do:
.. automodapi:: mypackage.mymodule
and it will generate the table and individual pages for each function.
Disclaimer: I am an author of sphinx-automodapi

In the answer to Sorting display by class using sphinx with 'autodoc'? it is explained how to generate documentation for classes with one page per class, using autosummary with autosummary_generate=True.
This mechanism works for functions too. Use something like this:
EoN API documentation
=====================
.. currentmodule:: EoN
.. autosummary::
:toctree: functions
my_function1
my_function2
my_function3
...
You have to enumerate each function in the autosummary directive, but the corresponding *.rst files are generated automatically (in the functions subdirectory).

Automatically create a toctree for autodoc classes in Sphinx

I'm looking to increase the documentation in one of my libraries. I've been using sphinx to help build the documentation and recently started exploring the autodoc extension.
It seems like in most professional documentation, each class documentation page has a list of all the documented methods with links at the top. Or, in other words, a toctree at the top with hyperlinks to each of the more in depth method documentation.
Is there a way to automatically create this toctree for each of the classes being documented with autodoc?

In your conf.py file for sphinx add
extensions = ['sphinx.ext.autosummary',]
# NOTE: Don't overwrite your old extension list! Just add to it!
autodoc_default_flags = ['members']
autosummary_generate = True
I put the toctree in my index.rst, and it looks like this:
.. autosummary::
:toctree: stubs
Class1
Class2
Class3
See this example for the conf.py settings
and this example for an example of the toctree.
Hope that helps!

How do I get Sphinx to generate 'contents.rst'?

The Sphinx templates I use (for example sphninxdoc or sphinx13) have a link to a 'contents.rst' file; however, though this file is documented as "special", I don't see a way to generate it.
Is there a way to get Sphinx to generate 'contents.rst' automatically, or do I need to generate it manually?

When I came to this page, I needed to fix the .readthedocs.yml. My sphinx configuration path was missing the "source" part:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
Within the config, I have
# The master toctree document.
master_doc = 'index'

The "special" contents.rst file that is mentioned in the question is not generated automatically. It is written like any other reST file and is stored in the Python repository: https://github.com/python/cpython/blob/master/Doc/contents.rst.
The Python documentation main page at http://docs.python.org/release/2.7/index.html has a Complete Table of Contents link that points to contents.html, which is built from contents.rst.
The source for the Sphinx documentation includes a similar contents.rst: https://github.com/sphinx-doc/sphinx/blob/master/doc/contents.rst.