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 9 hours ago | parent [-]

> 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 7 hours ago | parent [-]

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 4 hours ago \| parent [-]
		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.