Comment by westurner

11 hours ago

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

3 comments

westurner

westurner 11 hours 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-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 4 hours 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 2 hours 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