[Python-Dev] Documenting the private C API (was Re: Questions about signal handling.)

[Nick Coghlan]

On Wed, 26 Sep 2018 at 00:33, Barry Warsaw <barry at python.org> wrote:
>
> On Sep 25, 2018, at 10:18, Antoine Pitrou <solipsis at pitrou.net> wrote:
> >
> > Not really.  Many are just like "static" (i.e. module-private)
> > functions, except that they need to be shared by two or three different
> > C modules.  It's definitely the case for _PyEval_SignalReceived().
>
> Purely static functions which appear only in the file they are defined in are probably fine not to document, although I do still think we should take care to comment on their semantics and external behaviors (i.e. reference counting).  But if they’re used in multiple C files, then I think they *can* deserve placement within the documentation.

We run into this problem with the test.support helpers as well (we
have more helpers than just those in the docs, but the others tend to
rely on contributors and/or PR reviewers having looked at other tests
that already use them).

Fleshing out on the "internals" docs idea that some folks have mentioned:

1. Call it "Doc/_internals" and keep the leading underscore in the
published docs
2. Use it to cover both C internals and Python internals (such as test.support)
3. Permit use of autodoc tools that we don't allow in the main docs
(as these docs would be for CPython contributors, so the intended
audience for the docs is the same as the audience for the code)
4. Potentially pull in some specific files and sections from the
source code as literal include blocks (as per
http://docutils.sourceforge.net/docs/ref/rst/directives.html#include)
rather than rewriting them

Cheers,
Nick.

P.S. While it wouldn't be usable directly,
https://github.com/jnikula/hawkmoth at least demonstrates the
principle of extracting Sphinx API docs from C source files.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia