Steph-Chong
commented
3 months ago Listing all of the files in scores/docs/, and noting whether or not there are links that need changing:
- [x] SECURITY.md: changes not needed
- [x] api.md: changes not needed
- [x] coding_practices.md (note: this file is not the readthedocs index): changes not needed, as existing links were already relative
- [x] conf.py: changes not needed
- [x] contributing.md: changes not needed, as all links either external, already relative, or linking to specific sections of GitHub that are not contained within the docs folder
- [x] data.md: changes not needed, as all links are external
- [x] included.md: changes are needed for:
- [x] links to APIs (see issue #512, PR #514 merged)
- [x] links to tutorials (see issue #513, PR #516 merged)
- [x] index.md: changes not needed
- [x] installation.md: changes not needed, as no links at all on this page
- [x] maintainer.md: changes not needed, links either external or were already relative
- [x] related_works.md: changes not needed, as all links are external
- [x] requirements/txt: changes not needed
- [ ] tutorials:
- [x] Tutorial Gallery: changes not needed
- [x] Tutorial README.md: changes not needed
- [ ] Individual tutorials - still needs to be checked if any tutorials require updated links
tennlee
I will raise new issues for each part of this so things can be done incrementally. The documentation is currently set up with fully-qualified URLs for almost everything, for historical reasons that made sense at the time, some of which are still relevant. However, we can now move to a more flexible approach if we are careful as we go.
Readthedocs has now been set up as follows:
Links on the README should remain fully-qualified, because they need to be consistent across the raw markdown, github, reathedocs, PyPI and a few other places. They should be updated to point to "stable" where relevant.
Links in the general documentation (i.e., what sphinx builds), can now be made relative in most cases. The front page will remain fully-qualified as it is drawn in from the README and the only way around this I know would be to fully duplicate the README file contents and keep it up to date. This approach hasn't worked too well in the past.
We were originally trying to keep the readthedocs pages and github rendering both working nicely. However, for multiple reasons, it's just not reasonable to keep the github renderings nice. Github doesn't support the relevant table formatting, and doesn't render all the stuff in the tutorials either. As such, we will optimise for readthedocs and (where relevant) human-readable source files.
As such, all that documentation (aside from the README and the tutorials) can now move to using relative linking.
The tutorials are a whole nother thing. Links within the tutorials should be linked against stable or left as-is. Tutorials need to work as jupyter notebooks (i.e in jupyter lab), in readthedocs, in binder, in nbviewer (in two different forms), and ideally when viewed in github (which is not entirely possible). Further, the tutorials render slightly differently in all six of these locations.
Nonetheless, moving to relative links where we can will make the API documentation and sphinx documentation more portable, be able to support multiple release version more easily, and should be simpler to develop and test going forward.