automodule docs

[falexwolf]

I'm probably not seeing something very simple: https://scanpy.readthedocs.io/en/latest/api/scanpy.external.html#module-scanpy.external renders fine whereas https://scanpy.readthedocs.io/en/latest/api/scanpy.api.html#module-scanpy.api https://scanpy.readthedocs.io/en/latest/api/scanpy.plotting.html#module-scanpy.plotting both append an auto-generated list of all functions and classes defined in the module. As there is an annotated manual list already, we obviously don't want this.

[flying-sheep]

Well, scanpy/__init__.py, scanpy/api/__init__.py and scanpy/external/__init__.py don’t contain .. automodule:: whereas scanpy/plotting/__init__.py and docs/api/index.rst do.

So just removing the automodule lines should fix this.

[falexwolf]

Hm, simply removing .. automodule:: scanpy is not possible in the case of scanpy/plotting/__init__.py as then sphinx doesn't seem to know anymore where all the pl.* functions come from.

Also, docs/api/index.rst renders completely fine: https://scanpy.readthedocs.io/en/latest/api/index.html. The problem is with scanpy/api/__init__.py (which doesn't contain ..automodule::, as we're just documenting the functions defined in that directory) and scanpy/plotting/__init__.py (which does contain it, as we're documenting 'scanpy-level' functions).

[flying-sheep]

I see! OK, so .. automodule doesn’t by default include the members, and we don’t have autodoc_default_options set.

All three directives [(automodule and so on)] will by default only insert the docstring of the object itself

However I don’t understand what you mean by

as then sphinx doesn't seem to know anymore where all the pl.* functions come from

So will it simply not link them? Because that can have other reasons as well…

[flying-sheep]

Hmm, maybe it has to do with some docstring bugs, let’s check. e.g. this is pretty borked, I’ll fix it: https://icb-scanpy.readthedocs-hosted.com/en/latest/api/scanpy.external.exporting.cellbrowser.html

[flying-sheep]

Docutils says that all kinds of imports fail in plotting, hmm…

/edit: ah, of course.

1. autosummary generates docs/api/scanpy.plotting.rst containing a header and

   .. automodule:: scanpy.plotting
   
   .. autosummary::
   
      clustermap
      ...

2. the automodule directive renders the docstring from plotting/__init__.py and then the autogenerated list of functions.

To fix this, we need to create scanpy.plotting.rst ourselves. Will do so

[flying-sheep]

Fixed in 9861b66128c0a3a04df9d784e26664874dd23b1b

[falexwolf]

Thank you, great!