[Python-Dev] Documenting the private C API (was Re: Questions about signal handling.)
On Tue, Sep 25, 2018 at 3:27 PM Barry Warsaw <barry at python.org> wrote:
> On Sep 25, 2018, at 12:09, Yury Selivanov <yselivanov.ml at gmail.com> wrote:
> > My main concern with maintaining a *separate* documentation of
> > internals is that it would make it harder to keep it in sync with the
> > actual implementation. We often struggle to keep the comments in the
> > code in sync with that code.
> Well, my goal is that the internal API would show up when I search for function names on docs.python.org. Right now, I believe the ?quick search? box does search the entire documentation suite. I don?t care too much whether they would reside in a separate section in the current C API, or in a separate directory, listed or not under ?Parts of the documentation? on the front landing page. But I agree they shouldn?t be intermingled with the public C API.
An idea: it would be cool to have something like Sphinx autodoc for C
headers to pull this documentation from source.