NCAS-CMS
Update links to point to new home of cf-plot documentation
As I realised when guiding our summer student this week, the cf-python documentation still links to the old cf-plot documentation under the 'ajheaps' userspace, except for the README. I had updated the README some months ago but neglected to do a full sweep of the codebase to update all references to the old cf-plot docs, so here is that mass update.
@davidhassell, feel free to just sanity check as a review since this is very self-contained, specific and non-controversial. Thanks.
But do we want the "build" in the URLs? Should we have (e.g.) https://ncas-cms.github.io/cf-plot/gopen.html, a la cf-python?
Good spot. Ideally not, but I like to separate out the built and source documentation into their own directories to keep them self-contained for dev and building and to do so I need to put the built content into a different directory. So unless I can find a way to point the root from https://ncas-cms.github.io/cf-plot/build/ to https://ncas-cms.github.io/cf-plot/, this is how it needs to be...
Hi Sadie - could you structure it like we do in cf-python, perhaps?
I could, but then I would have to go and change all of the links I've updated with bulid/ elsewhere (e.g. for the CF Conventions software page, etc.) for the sake of getting them updated quickly.
Having a separate build directory really helps me with general development, e.g. when you grep in the docs directory for the setup of e.g. the cf-python docs you have a mixture of HTML and RST directories and files and it is never clear what is a permanent codebase directory or a generated build directory in there to me from that, so I am not just being a pain (at least, not trying to be)! :laughing:
For now I think we have three options on this note:
- I can put the merge of this on hold and I can expedite my plans to work out how to redirect to remove the
build/component from the URL even though that is where the built content will live, which isn't ideal in the link for sure (even though having it as a directory is useful as per above) so that we can get bothhttps://ncas-cms.github.io/cf-plot/build/<subpaths>andhttps://ncas-cms.github.io/cf-plot/<same subpaths>working and I can use the latter links here (and in general, going forward). - You could allow this PR to go in as-is with the
build/in the URL, which we appreciate is not ideal but does work. - I could indeed change the structuring but then suffer from the issues I describe above for cf-plot and need to fix the links to remove the
build/elsewhere.
I prefer (1) since then I'll be getting something done I have been putting off and we will both be happy (I think?), what do you think?
I should add, it's a shame GitHub Pages doesn't let me serve the docs site from docs/build/ rather than just docs, which would solve the problem seamlessly, but from some investigation it does not, probably for good reason.
Oh wait! I have a new fourth option that is probably the best way forward:
- I don't build the content locally and to the codebase, I use GitHub Actions to build and push it to a GitHub pages branch which is the one that gets hosted. I've seen this done with numerous other projects and it seems a really clean way to do the build. Though, that will break the links elsewhere.
In the interests of getting this fixed for the next release, I will merge this - but I have noted that I should ideally get the URL fr the cf-plot docs updated from https://ncas-cms.github.io/cf-plot/build/... to https://ncas-cms.github.io/cf-plot/... without the build endpoint to the URL, ideally without having to put the source and built content in the same directory, probably via setting up the docs building via a GitHub Actions job, as per my previous comments.