Trying out improvements to docs/make.jl

[tomchor]

This PR tries out a couple of changes in the docs/make.jl file:

1. Adds the main project's environment to the docs (this prevents the versions of deps in Manifest.toml and docs/Manifest.toml from being different, which was happening for Oceananigans)
2. Pushes previews to a different branch, so that hopefully we can still see previews, but cleaning them up will be a matter of deleting the branch

[tomchor]

Pushing the previews to the doc-previews branch in the sense that the branch gets created and the docs do appear there. But, as expected, the preview doesn't appear in https://tomchor.github.io/Oceanostics.jl/previews/PR141 since github pages is served by the gh-pages branch.

However, you can still check the branch out locally and inspect the docs, which I think is better than the alternatives (i.e. not having a preview at all, or pushing previews to the gh-pages branch).

[tomchor]

@navidcy I also realized that the prevoius make.jl wasn't actually deleting the .nc and .jld2 files. (I fixed this in https://github.com/tomchor/Oceanostics.jl/pull/141/commits/5d122486b6737020697d959028c765d46ecb8e11 I think using your algorithm!)

As a result the repo size is already pretty big (I think ~200 MB?). I think you cleaned the OceananigansDocumentation repo before under similar circumstances, no? Can you point me to a simple guide on how to do this cleaning? Every how-to I see online ends up being more complex than I'm comfortable with (i.e. I don't know enough git to be sure I won't mess up important things :grimacing:).

[navidcy]

I don't see the docs/Manifest.toml.

[navidcy]

@navidcy I also realized that the prevoius make.jl wasn't actually deleting the .nc and .jld2 files. (I fixed this in 5d12248 I think using your algorithm!)

As a result the repo size is already pretty big (I think ~200 MB?). I think you cleaned the OceananigansDocumentation repo before under similar circumstances, no? Can you point me to a simple guide on how to do this cleaning? Every how-to I see online ends up being more complex than I'm comfortable with (i.e. I don't know enough git to be sure I won't mess up important things 😬).

Are all the large files you'd like to get rid off in a branch other than main?

[tomchor]

I don't see the docs/Manifest.toml.

There isn't one. It's only created when the docs run (but it's never committed). I think this was something you suggested, but we can commit a docs/Manifest.toml if you think it's best.

[tomchor]

@navidcy I also realized that the prevoius make.jl wasn't actually deleting the .nc and .jld2 files. (I fixed this in 5d12248 I think using your algorithm!) As a result the repo size is already pretty big (I think ~200 MB?). I think you cleaned the OceananigansDocumentation repo before under similar circumstances, no? Can you point me to a simple guide on how to do this cleaning? Every how-to I see online ends up being more complex than I'm comfortable with (i.e. I don't know enough git to be sure I won't mess up important things grimacing).

Are all the large files you'd like to get rid off in a branch other than main?

Unless I'm missing something, yes. They're all the output files that are in gh-pages.

[navidcy]

Unless I'm missing something, yes. They're all the output files that are in gh-pages.

OK, we can deal with this easily. The tricky git bits come when you want to delete a file but keep all the rest of the git history. That involves modifying every git commit! That would be the case if we had accidentally committed a .nc file on main.

But with gh-pages nobody cares about the history of the commits. We can create a new orphan branch and then copy all the contents from gh-pages leaving out the big files, commit and push. I've done this many times -- this is how I'm cleaning the previews history from the gh-pages branch in OceananigansDocumentation repo.

[tomchor]

Unless I'm missing something, yes. They're all the output files that are in gh-pages.

OK, we can deal with this easily. The tricky git bits come when you want to delete a file but keep all the rest of the git history. That involves modifying every git commit! That would be the case if we had accidentally committed a .nc file on main.

But with gh-pages nobody cares about the history of the commits. We can create a new orphan branch and then copy all the contents from gh-pages leaving out the big files, commit and push. I've done this many times -- this is how I'm cleaning the previews history from the gh-pages branch in OceananigansDocumentation repo.

Okay, I'm not sure if I follow everything, but here's my best guess.

1. Locally create an orphan branch with git checkout --orphan gh-pages
2. Copy the contents of gh-pages without the big files over to it
3. Delete gh-pages from github (obviously keep it locally)
4. Push the local orphan branch to github's gh-pages, so replace the old one.

Is that what you mean?

Also, if it's easier for you to just do it than it is to explain to me, feel free! I think all the files are .nc in the generated directory.

e.g.: https://github.com/tomchor/Oceanostics.jl/tree/gh-pages/v0.11.2/generated

[navidcy]

I can do it!

It's not quite that... I would be a bit more cautious... I would create an orphan branch called gh-pages-new and push that up and when all is good rename the branches to gh-pages -> gh-pages-old and gh-pages-new -> gh-pages. Then ensure the GitHub pages deploys the new branch and only after delete the old one.

[navidcy]

I'll do it after this PR is merged ;)

[tomchor]

I'll do it after this PR is merged ;)

Thanks, I appreciate it! :)

lmk if there's anything else that needs changing in this PR. From my end I think this is ready.