Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document Python C extensions #100

Closed
martingalloar opened this issue Feb 21, 2017 · 1 comment
Closed

Document Python C extensions #100

martingalloar opened this issue Feb 21, 2017 · 1 comment

Comments

@martingalloar
Copy link

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 Allow which toctree node the entries are placed under to be configurable #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
Copy link
Collaborator

AWhetter commented Aug 2, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants