2 ms·
That's why three different procedures for docs? Python docs procedures: (0) Devguide, (1) PEPs w/ front matter in RST, (2) RST in /Doc with Sphinx, (3) MD and
by westurner 9mo ago
That's why three different procedures for docs?
Python docs procedures: (0) Devguide, (1) PEPs w/ front matter in RST, (2) RST in /Doc with Sphinx, (3) MD and TXT in /InternalDocs without a toctree
The .. warning: or even admonition directives could be used for indicating that docs under /internals are not public API and can change with or without a PEP; though that should also or at least be indicated in the source unless that's a given expectation that not marked public APIs are not to be considered stable
- shakna 9mo agoHow many, many times has a project said, "Don't use, internal only", only for it to become an industry-wide common "trick"? Saying "here be dragons" is not enough to discourage people whose job it is to be creative.
- westurner 9mo agoThat's the bad kind of lazy. It is advantageous to format, interlink, and create a table of contents for documentation. I doubt anyone would advocate for removing the Makefile and conf.py from /Doc. That a document describes something internal does not mean that it should be excluded from the docs. Is there a consistent standard for whether something is internal or external to the CPython project? Aren't there already internal things documented in /Doc? Should they be removed from the docs build then? Or moved to an internal folder with a DRY additional toctree?