Open define-private-public opened 2 months ago
see https://github.com/orgs/community/discussions/86715 for more info
[ ] 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.
[ ] 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
.)
[ ] 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.
rst2myst
rst2myst
```{contents}
:local:
:depth: 2
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.
[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,
.. contents::
stopped working on my repositories, too. It would be good if someone could fix it, please. Thanks.
Should the TOC failure be its own new issue, or fall under this umbrella one?
I confirm, that .. contents::
stopped working on my directories as well
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