Document Python C extensions

[martingalloar]

My project (pysap) has two components: a pure python library and a C extension. Currently I'm using apidoc for building both, but wanted to switch to sphinx-autoapi as it's cleaner and seems a better approach than importing the modules.

I've already started playing with it in the autoapi branch, by using sphinx-autoapi for the python library and keeping apidoc for the C extension, but I don't see a clear way of integrate both documentation trees.

I'm wondering what would be the best way to support this kind of scenarios. Some ideas:

• have an API tocree node wich refers to the C extension documentation produced via apidoc, and let sphinx-autoapi entries be placed there (in the same line than #97).
• directly implement some kind of support for C extensions and/or allow multiple instances of sphinx-autoapi to be configured (e.g. one folder for a Python doc, another for a C extension one, etc.)
• allow customization of the automatically inserted toctree index to allow addition of externally generated API docs (e.g. via a template)

Any thoughts?

[AWhetter]

We're adding support for autodoc style directives. Would that cater for your use case? That way you can write your pure Python entries with the directives, and use normal Sphinx directives to document that C extension. There's less automation this way but it would allow you to document both the pure python and C extension in your documentation.