4 ms·

vstinner's Python docs; "Unofficial Python Development (Victor's notes) documentation" > Garbage Collector > "Implement the GC protocol in a type": https://pyt

vstinner's Python docs; "Unofficial Python Development (Victor's notes) documentation" > Garbage Collector > "Implement the GC protocol in a type": https://pythondev.readthedocs.io/garbage_collector.html#implement-the-gc-protocol-in-a-type https://pythondev.readthedocs.io/garbage_collector.html#impl... Python Developer's Guide > "CPython's internals": https://devguide.python.org/internals/index.html https://devguide.python.org/internals/index.html Python/cpython//InternalDocs/README.md > "CPython Internals Documentation": https://github.com/python/cpython/blob/main/InternalDocs/README.md https://github.com/python/cpython/blob/main/InternalDocs/REA...

westurner 9mo ago
IDK why /InternalDocs/ instead of /Doc/internals/ ? ( `ln -s` works with Mac/Lin/WSL. ) Ideally what's in InternalDocs/ would be built into the docs.python.org docs . Is it just that markdown support in sphinx is not understood to exist? Sphinx has native markdown support. Sphinx does not have native MyST Markdown support. To support MyST Markdown in a sphinx-doc project, you must e.g. `pip install myst_parser` and add "myst_parser" to the extensions list in conf.py. MyST Markdown supports docutils and sphinx RestructuredText roles and directives: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html https://myst-parser.readthedocs.io/en/latest/syntax/roles-an... Directive in ReStructuredText .rst: .. directivename:: arguments :key1: val1 :key2: val2 This is directive content Directive in MyST Markdown .md: ```{directivename} arguments :key1: val1 :key2: val2 This is directive content ``` RestructuredText Role, MyST Markdown Role: :role-name:`role content` {role-name}`role content` Sphinx resolves reference labels at docs build time, so that references will be replaced with the full relative URL to the path#fragment of the document where they occur; in ReStructuredText and then MyST Markdown: .. _label-name: (label-name)= :ref:`Link title <label-name>` {ref}`Link title <label-name>`
- shakna 9mo ago
  > Ideally what's in InternalDocs/ would be built into the docs.python.org docs . If you expose internals in documentation, then people depend on internals. And when you break it, because it isn't meant to be tracked by any kind of API, there are wonderful groups who will sue you (usually under "devaluation").
  - 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 ago
      How 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 ago
        That'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?

westurner 9mo ago

IDK why /InternalDocs/ instead of /Doc/internals/ ? ( `ln -s` works with Mac/Lin/WSL. ) Ideally what's in InternalDocs/ would be built into the docs.python.org docs . Is it just that markdown support in sphinx is not understood to exist? Sphinx has native markdown support. Sphinx does not have native MyST Markdown support. To support MyST Markdown in a sphinx-doc project, you must e.g. `pip install myst_parser` and add "myst_parser" to the extensions list in conf.py. MyST Markdown supports docutils and sphinx RestructuredText roles and directives: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html https://myst-parser.readthedocs.io/en/latest/syntax/roles-an... Directive in ReStructuredText .rst: .. directivename:: arguments :key1: val1 :key2: val2 This is directive content Directive in MyST Markdown .md: ```{directivename} arguments :key1: val1 :key2: val2 This is directive content ``` RestructuredText Role, MyST Markdown Role: :role-name:`role content` {role-name}`role content` Sphinx resolves reference labels at docs build time, so that references will be replaced with the full relative URL to the path#fragment of the document where they occur; in ReStructuredText and then MyST Markdown: .. _label-name: (label-name)= :ref:`Link title <label-name>` {ref}`Link title <label-name>`

shakna 9mo ago
> Ideally what's in InternalDocs/ would be built into the docs.python.org docs . If you expose internals in documentation, then people depend on internals. And when you break it, because it isn't meant to be tracked by any kind of API, there are wonderful groups who will sue you (usually under "devaluation").
- 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 ago
    How 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 ago
      That'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?