from . import tl
from . import pl
from . import pp

from .. import _exporting as exporting

import sys
from .. import utils
utils.annotate_doc_types(sys.modules[__name__], 'scanpy')
del sys, utils


__doc__ = """\
External API
============


Import Scanpy's wrappers to external tools as::

   import scanpy.external as sce

Preprocessing: PP
------------------

Batch effect correction
~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   pp.bbknn
   pp.mnn_correct

Imputation
~~~~~~~~~~

Note that the fundamental limitations of imputation are still under `debate
<https://github.com/theislab/scanpy/issues/189>`__.

.. autosummary::
   :toctree: .

   pp.dca
   pp.magic


Tools: TL
----------

Embeddings
~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.phate
   tl.palantir

Clustering and trajectory inference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.phenograph

Gene scores, Cell cycle
~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.sandbag
   tl.cyclone


Plotting: PL
------------

.. autosummary::
   :toctree: .

   pl.phate
   tl.palantir


Exporting
---------

.. autosummary::
   :toctree: .

   exporting.spring_project
   exporting.cellbrowser
"""

scanpy/external/__init__.py
from . import tl
from . import pl
from . import pp

from .. import _exporting as exporting

import sys
from .. import utils
utils.annotate_doc_types(sys.modules[__name__], 'scanpy')
del sys, utils


__doc__ = """\
External API
============


Import Scanpy's wrappers to external tools as::

   import scanpy.external as sce

If you'd like to see your tool included here, please open a `pull request <https://github.com/theislab/scanpy>`_!

Preprocessing: PP
------------------

Batch effect correction
~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   pp.bbknn
   pp.mnn_correct

Imputation
~~~~~~~~~~

Note that the fundamental limitations of imputation are still under `debate
<https://github.com/theislab/scanpy/issues/189>`__.

.. autosummary::
   :toctree: .

   pp.dca
   pp.magic


Tools: TL
----------

Embeddings
~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.phate
   tl.palantir

Clustering and trajectory inference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.phenograph

Gene scores, Cell cycle
~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   tl.sandbag
   tl.cyclone


Plotting: PL
------------

.. autosummary::
   :toctree: .

   pl.phate
   tl.palantir


Exporting
---------

.. autosummary::
   :toctree: .

   exporting.spring_project
   exporting.cellbrowser
"""

scanpy/external/__init__.py
diff --git a/.gitignore b/.gitignore
index ac4119e4de..4c4ad3ee7b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 # Docs
 /docs/_build/
 /docs/api/scanpy.*.rst
+/docs/external/scanpy.*.rst
 !/docs/api/scanpy.api.rst
 !/docs/api/scanpy.api.AnnData.rst
 !/docs/api/scanpy.plotting.rstk
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 044864e3eb..eb0a706ca2 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -307,7 +307,6 @@ Further modules
 .. autosummary::
    :toctree: .
 
-   external
    api
    plotting
 
diff --git a/docs/external/index.rst b/docs/external/index.rst
new file mode 100644
index 0000000000..f4eee974ef
--- /dev/null
+++ b/docs/external/index.rst
@@ -0,0 +1 @@
+.. automodule:: scanpy.external
diff --git a/docs/index.rst b/docs/index.rst
index 36299ee077..47c1634791 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,4 +16,5 @@ If Scanpy is useful for your research, consider citing `Genome Biology (2018) <h
    basic_usage
    installation
    api/index
+   external/index
    references
diff --git a/scanpy/external/__init__.py b/scanpy/external/__init__.py
index 10f2c40cfa..15fcbdb2c2 100644
--- a/scanpy/external/__init__.py
+++ b/scanpy/external/__init__.py
@@ -19,6 +19,8 @@
 
    import scanpy.external as sce
 
+If you'd like to see your tool included here, please open a `pull request <https://github.com/theislab/scanpy>`_!
+
 Preprocessing: PP
 ------------------
 

Give `external` higher billing in the docs?
At the moment external modules are kind of hidden in the docs. I think it'd be worth making them more visible (at least on the same page as everything else). I've been giving this a shot, but have hit the limit of my sphinx/ rst abilities.

Two ideas for how they could be more discoverable:

* They get their own heading under `api`
* They're mixed in with everything else (so everything stays organized by topic), but their names are prepended with `sce` while scanpy functions are prepended with `sc`.
