[westurner]

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#impl...

Python Developer's Guide > "CPython's internals": https://devguide.python.org/internals/index.html

Python/cpython//InternalDocs/README.md > "CPython Internals Documentation": https://github.com/python/cpython/blob/main/InternalDocs/REA...

[westurner]

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-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]

> 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]

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]

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]

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?