Add autodoc style directives for autoapi usage

[agjohnson]

Using directives for this will allow for manual inclusion of auto api docs. This should still allow for a full path to be created, perhaps as a secondary option once we have this feature.

[agjohnson]

I feel like this integration could either integrate with autodoc or replace some of the options. We should explore what work this would take. For instance, if autodoc has the python execution abstracted in a way that we can override with a parse only solution, we could be really close to a drop in replacement without reproducing our own directives/etc.

[AWhetter]

It looks like the only way to override the existing autodoc directives would be to use Sphinx.add_autodocumenter (http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_autodocumenter). It would mean that if autodoc is loaded then you would get warnings about the directives getting registered more than once. There's also the option of using Sphinx.registry.add_documenter but Sphinx.registry is not documented even though it is a public attribute.

We could add something that listens to the source-read event and (optionally) transforms autodoc directives into our own equivalent directives. Without doing a lazy find and replace, that would mean parsing rst though.

In either case, I think there's value in having our own directives so I'll implement them and we can take our time making a decision on the above.

[ericholscher]

Yea, having our own version of the directives is a good start 👍

Once we have our own version solid, then we can have an option to replace the existing ones if we wanted. It might require some monkeypatching, or submitting a PR to Sphinx itself, to make it easier to replace them.