Comment by 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>`