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

Nick Coghlan ncoghlan at gmail.com
Fri Sep 28 10:29:44 EDT 2018

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 PyEvalSignalReceived(). 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

More information about the Python-Dev mailing list