search

NCAS-CMS / cf-python

A CF-compliant Earth Science data analysis library
http://ncas-cms.github.io/cf-python
MIT License
125 stars 19 forks source link

Update links to point to new home of cf-plot documentation #813

Open sadielbartholomew opened 1 month ago

sadielbartholomew commented 1 month ago

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.

sadielbartholomew commented 1 month ago

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...

davidhassell commented 1 month ago

Hi Sadie - could you structure it like we do in cf-python, perhaps?

sadielbartholomew commented 1 month ago

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:

  1. 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 both https://ncas-cms.github.io/cf-plot/build/<subpaths> and https://ncas-cms.github.io/cf-plot/<same subpaths> working and I can use the latter links here (and in general, going forward).
  2. 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.
  3. 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?

sadielbartholomew commented 1 month ago

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.

sadielbartholomew commented 1 month ago

Oh wait! I have a new fourth option that is probably the best way forward:

  1. 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.