Hi John, On Tue, Jun 15, 2021, at 03:03, John Lee wrote:
I wanted to get some feedback regarding some changes to the building of the docs. Juan asked myself and a colleague Vinicius Cerutti to look after a feature request (posted on Zulip) for a warning banner when a user is not on the docs for the most recent release. A nice solution for this would be https://goerz.github.io/docs_versions_menu/v0.4.1/. This builds on the efforts of doctr, a tool that, while similar to readthedocs, provides a lot of flexibility in the build of the documentation: https://drdoctr.github.io/. The sphinx theme (alabaster) used by doctr is quite similar to the current theme used for the scikit-image docs so there won't be too much of a change to the aesthetics of the site. How do people feel about such a change? The alternative would be to add a custom javascript snippet to implement this... that would be an easy enough quick fix if people aren't fans of such a docs-infrastructure migration,
Thank you for your help with the scikit-image infrastructure! This work is so important, and way overdue. In terms of themes, we should migrate to the pydata-sphinx theme as soon as possible. The community is standardizing on it, and that is where new features will be developed. I know, e.g., that they have a grant proposal submitted that would fund development on, among other things, a versioning bar. As you mention, it's already trivial to implement it in the simplest way possible: https://networkx.org/documentation/latest/ Ideally, the version bar should find "nearest" pagest in older versions—which is what the PyData Sphinx theme team will build. I.t.o. builders: I am opposed to using anything other than GitHub Pages steps (or similar) to build and upload the documentation to GitHub. We used some of these tools before, and the magic behind which they hide the build steps is a great hindrance for new developers trying to understand the overarching process. Thanks again for your work on this! Best regards, Stéfan