logoalt Hacker News

westurner • yesterday at 5:51 PM • 1 reply • view on HN

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

Replies

westurner • yesterday at 6:09 PM

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>`
➕ show 1 reply