search

canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
13 stars 35 forks source link

Orphan `setup-script` #171

Closed pmatulis closed 7 months ago

pmatulis commented 7 months ago

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.

ru-fu commented 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.

pmatulis commented 7 months ago

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.

ru-fu commented 7 months ago

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.

pmatulis commented 7 months ago

Okay so you are using it and it works for you. Alright, I'll just add it then.