Closed pmatulis closed 7 months ago
This will make it extremely difficult to find the page. I don't see it as an issue that GitHub displays the toctree directive - GitHub rendering for RST isn't perfect, and that's just how it is. It also makes it clear that there is a subpage.
That being said, the cleanest way IMO would be to include the content of the file in the main readme instead of hiding it on a subpage.
We can indeed include it in the README. However I've always held reservations about it; I don't consider it to be of much value. Yet by including it we are obliged to ensure it stays in sync with the pack's evolution. And having a perpetual Beta label is also something we need to avoid.
I find it much easier to set things up with the script - and since everybody will do this on either a fresh repo or a branch of their repo, I don't see any risks in using the script. So I wouldn't even consider it beta.
Okay so you are using it and it works for you. Alright, I'll just add it then.
Deal with poor GitHub support for RST.
The setup-script is currently a sub-page to the README, according to a conscious decision. This required a
toctree
directive in the README. However, in GitHub the latter gets exposed in the rendered HTML.For now, orphan the setup-script page until we decide what to do. As-is, the README's appearance in GitHub is intolerable. The fact that this script is considered beta at this time lessens the impact of this change.
Also fix the link to setup-script in the body of the README.