Repository: scverse/scanpy

Issue:
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`.


Discussion:
Hm, they're mentioned in the note at the very top, and there are cross-references within the page. They have a separate page just as plotting.

I'm happy to give them a separate heading, just like plotting has. I wouldn't want them to be mixed in. I expect that list of external tools to potentially become quite long at some point. I'd also prefer them to stay on a separate page.
I've got two main reasons for thinking they should be more visible:

1. If I'm trying to find what tools are available through scanpy for a certain task, it should be very obvious where that might be available.  For example, if I want to know what's available for batch correction, I (the user) am probably not too fussed about whether it's in the scanpy codebase or not.
2. As a method developer, it'd encourage me to integrate my method if I saw it'd be highly visible and that other people were doing it. Right now there are links, but users still have to go to see the notes with those links, go to a separate page, and scroll for a bit to see any particular method. 

Another strategy could be a top level `External API` heading underneath the `API` heading? Then there could be an expandable table of contents (how I typically navigate the site) to get an idea of what's there.
I'm not against giving the external module higher visibility. I'm absolutely for it. I just don't want to mix all functions together.

You mean: adding `External API` in the top-level navigation bar? That sounds very right!
Great!

Yeah, and having it's table of contents following the general layout from
`API`.

On Thu, Apr 4, 2019 at 3:02 PM Alex Wolf <notifications@github.com> wrote:

> I'm not against giving the external module higher visibility. I'm
> absolutely for it. I just don't want to mix all functions together.
>
> You mean: adding External API in the top-level navigation bar? That
> sounds very right!
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/theislab/scanpy/issues/588#issuecomment-479741789>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AH221AXVtyyTekvt2ecg7pCxk7oKovyOks5vdXlYgaJpZM4cb1Lm>
> .
>


Resolving patch:
diff --git a/scanpy/external/__init__.py b/scanpy/external/__init__.py
--- 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
 ------------------
 


Test patch: