reStructuredText is no longer rendering correctly.

[define-private-public]

I've got a README here which has an improperly scaled header image at the top: https://github.com/define-private-public/PSRayTracing

It's supposed to look like this: https://gitlab.com/define-private-public/PSRayTracing/-/blob/master/README.rst?ref_type=heads

It was working correctly on GitHub back in January: https://web.archive.org/web/20240101013527/https://github.com/define-private-public/PSRayTracing

[ml-evs]

see https://github.com/orgs/community/discussions/86715 for more info

[westurner]

• [ ] TST,REGR: the RST examples in docutils/docutils should work regardless of the rstcheck checker's output, if all existing RST that can't or won't be changed needs to work on GitHub where it has worked since GitHub launched.

  • https://github.com/docutils/docutils/blob/master/docutils/docs/ref/rst/restructuredtext.txt
  • https://github.com/docutils/docutils/blob/master/docutils/docs/ref/rst/roles.txt
  • https://github.com/docutils/docutils/blob/master/docutils/docs/ref/rst/directives.txt

• [ ] ENH: sphinx/jupyter-book support (FWIW, Sphinx supports .rst and .md documents with additional roles and directives. jupyter-book supports .rst, .md, and .ipynb jupyter notebooks with sphinx roles and directives. GitHub users build docs with GitHub Actions (and the RTD container which contains all of LaTeX preinstalled) and/or ReadTheDocs because GitHub .rst rendering can't/doesn't do Sphinx roles and directives that require at worst a second pass of a collection of documents per the .. toctree: directive or _toc.yml.)

[westurner]

• [ ] BUG,REGR: The rst .. contents directive no longer works?

  .. contents::
  

  RST .. contents: directives take arguments:
  https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents :

  .. contents::
     :depth: 2
     :local:
  

  :local: Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled.

  • [ ] UX: Hopefully I don't have to rewrite all of the existing RST docs or go somewhere else
    • rst2myst
    • https://docs.readthedocs.io/en/stable/guides/migrate-rest-myst.html#how-to-migrate-from-restructuredtext-to-myst-markdown
      • rst2myst
      • But myst markdown and myst's contents directive isn't supported by GitHub:

        ```{contents}
        :local:
        :depth: 2
        ```
        

        • https://jupyterbook.org/en/stable/structure/configure.html#add-a-within-page-table-of-contents
        • https://myst-parser.readthedocs.io/en/stable/index.html
        • mystjs (Myst in JS) seems to be redirecting. https://executablebooks.org/en/latest/blog/2023-02-09-announce-mystjs/#bringing-myst-to-javascript-with-a-new-partnership
          • [ ] ENH: JupyterLite, GitHub: get MyST Markdown to work in JS with or without WASM and there must be multi-document processing with a second pass in order to resolve inter-document links at build/compile/link/render time

The contents directive is one advantage of RST (and IIRC AsciiDoc and MediaWiki) over Markdown, because it autogenerates a Table of Contents (TOC). With Markdown there's no standard RST-directive like way, you have to use an Action like toc-generator or another tool in your build to scrape the headings out of the parse tree and generate nested <ul>s of links to fragment URIs within just the current document, for example an ideally-accessible README.

• https://github.com/marketplace/actions/toc-generator

• [x] ENH: GitHub added TOC support for Markdown files (and it looks like now also reStructuredText) with an unordered list button next to the file name,

  • [ ] UBY: but now you have to click/tap once before you can read a Table of Contents; there is now an additional click/tap before users can utilize the TOC information access optimization. https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/

[kourouklides]

.. contents:: stopped working on my repositories, too. It would be good if someone could fix it, please. Thanks.

[AndydeCleyre]

Should the TOC failure be its own new issue, or fall under this umbrella one?

[Ev2geny]

I confirm, that .. contents:: stopped working on my directories as well

[github-actions[bot]]

Stale issue message