Add a TOC to the README

[westurner]

What's the problem this feature will solve?

STORY: Users can skip to document headings with a linked Table of Contents in the sphinx docs

Describe the solution you'd like

• DOC: conf.py: html_sidebars = {...}
  • https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
  • examples:
    • https://github.com/wrdrd/docs/blob/6a1c1cc6f2b1d695e8ca70119da013fc28081bc8/docs/conf.py#L163C1-L183
    • https://sphinx-book-theme.readthedocs.io/en/stable/sections/sidebar-primary.html#control-the-left-sidebar-items
    • https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#primary-sidebar-left

Alternative Solutions

• DOC: README: Add a document-level TOC with mystmd syntax for the docutils .. contents:: RST directive like this:

  ```{contents}
  ```
  

  • https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-and-directives
  • https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
  • https://mystmd.org/guide/table-of-contents

Additional context

[webknjaz]

Furo is supposed to auto-include that. We should investigate why it's not doing that right now.