I’ve been messing around with some Python library docs recently, mostly trying to help out with gh-101100. I came to that party late. I only learned about that GitHub issue when someone posted, “Yay! We’re half done fixing the broken references in the documentation!” Needless to say, I have also not participated in any sort of documentation meetings. I’m just trying to keep a (small) iron in the fire. Based on that intro, these comments are probably more like something coming from Statler and Waldorf, not a totally coherent treatise on the subject.
I’ve noticed a couple things (mostly pointed out to me by others asking why I casually suppressed broken references).
- There seems to be a desire to document configure-generated C macros (think
Py_DEBUG). - Some topics seem to effectively be documented multiple times.
Let me address them in order.
For the young’uns reading this, I will suggest that GNU autoconf/configure, and before that Larry Wall’s interactive configure made possible the wildly portable software we are used to today. Before they came along, developing portable software was really difficult, even ignoring the lack of cross-platform GUI tools), much harder than it is now. Consequently, most software was never ported to even closely related platforms (think SunOS vs IRIX). Configure does several things, but for the purpose of this already too-long missive, in addition to auto-detecting various features of the platform, it records the user’s intentions in a couple ways: build parameters (e.g., wasi, MacOS framework, PGO stuff) and compile-time features (Py_DEBUG, being the most prominent in the Python ecosystem). In my opinion, compile-time features like Py_DEBUG are only a short-hand marker which record the user’s intent. They do not deserve independent documentation. They deserve to be recorded in the global index so people can discover what they are markers for when said people first stumble upon them. What does need documenting is the corresponding configure option and its sometimes complicated intent.
A simple example is --without-doc-strings. Configuring with that causes WITH_DOC_STRINGS to be unset. Maybe the C macro deserves an index entry (I’m ambivalent about such a simple thing). What does deserve documenting (and is documented) is the configure option. Mentioning its effect on the presence or absence of the C macro seems enough documentation of the macro to me.
Py_DEBUG is a somewhat different beast, simply because it’s so pervasive throughout the code base (199 hits by my count for Py_DEBUG vs 2 hits for WITH_DOC_STRINGS). Still, it’s just a simple marker for the user’s intent (--with-pydebug configure option and all that entails). The macro deserves an index entry, but it should point to documentation about debug builds, not some even short exposition on the macro itself. If this sort of procedure already exists, my apologies. I’ve just be crashing around like a bull in a china shop, discovering what breaks. The feedback I’ve received to me breaking things is that some people think the actual macros deserve documentation. I respectfully disagree. To summarize:
- Document the configure option, in gory detail, if necessary.
- Insert the bare minimum bit of Sphinx/ReST syntax in that vicinity to create an index entry for the macro(s) the option sets/unsets/modifies.
Which brings me to the second point. In going around in circles about Py_DEBUG, I stumbled on what seemed to be more-or-less two overlapping bits of documentation about what it means to create a debug executable. Doc/using/configure.rst has a “Python Debug Build” section which details many (hopefully all) effects of building a debugging executable. The following section, “Debug options,” enumerates all the configure options related to debugging. Doc/c-api/intro.rst also has a section on debug builds, where the relevant macros are the stars, not surprising because configure is now out of the picture. While not pure duplication, it does overlap with the section in configure.rst. It also mentions Misc/SpecialBuilds.txt, (also mentioned in the former rst file, though not in the section about debug builds, despite that it only contains a few bits about debug builds) which includes some of the same information. It’s not clear to me that all this discussion of debug builds needs to be scattered across (at least) three files, one of which isn’t strictly even part of the official documentation.
Cleaning that up will require more than inserting a few exclamation points or making sure macros have index entries. Maybe an issue should be opened. I would advocate for collapse of the general topic of debug builds to configure.rst and elimination of Misc/SpecialBuilds.txt altogether. Happy to create that if others agree. At the very least, it would give interested parties a more formal place to hash out this topic.
