Top level release index page
In PR 13886 I reworked the way the link to the release notes is generated. The current page is http://www.numpy.org/devdocs/release.html and the new page is https://8001-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/h... I don't like the "wall of text" in the current page. On the other hand, it is nice to use CTRL-F to search the page itself for answers to questions like "what release deprecated indexing by float", which is why I left the level-of-detail at 3 (1 - release, 2 - sections, 3 - item header). Should the level-of-detail be reduced to only single links to the release document? An alternative would be to render the contents as a collapsible list, which would require some javascript. Matti
On Tue, Jul 2, 2019 at 3:18 PM Matti Picus
In PR 13886 I reworked the way the link to the release notes is generated. The current page is
http://www.numpy.org/devdocs/release.html
and the new page is
https://8001-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/h...
I don't like the "wall of text" in the current page. On the other hand, it is nice to use CTRL-F to search the page itself for answers to questions like "what release deprecated indexing by float", which is why I left the level-of-detail at 3 (1 - release, 2 - sections, 3 - item header).
Should the level-of-detail be reduced to only single links to the release document?
I like your version, definitely nicer than what we have now, happy to go with your PR and level-of-detail 3 as is.
An alternative would be to render the contents as a collapsible list, which would require some javascript.
Hmm, custom JavaScript for navigating Sphinx-navigated docs seems wrong and is going to be a maintenance hassle at some point. Cheers, Ralf
On Tue, Jul 2, 2019 at 11:19 PM Matti Picus
In PR 13886 I reworked the way the link to the release notes is generated. The current page is
http://www.numpy.org/devdocs/release.html
and the new page is
https://8001-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/h...
I don't like the "wall of text" in the current page. On the other hand, it is nice to use CTRL-F to search the page itself for answers to questions like "what release deprecated indexing by float", which is why I left the level-of-detail at 3 (1 - release, 2 - sections, 3 - item header).
That seems a good compromise - certainly I have often used CTRL-F on release notes or change notes while tracing regressions - and having all the releases on one page makes this *so* much easier. Due to the way I typically use release notes, I would perhaps have just left the wall of text as is.
Should the level-of-detail be reduced to only single links to the release document?
I'm unclear what you are suggesting here.
An alternative would be to render the contents as a collapsible list, which would require some javascript.
Collapsible lists (which worked with CTRL-F searching) would be even better for balancing readability with utility, provided it was not too much trouble to implement and maintain of course. Peter
participants (3)
-
Matti Picus -
Peter Cock -
Ralf Gommers