Attempt at deploying all versions of the docs

[tomchor]

Per the deploydocs docs:

  versions determines content and order of the resulting version selector in the generated html. The following entries are valid in the versions vector:

    •  "v#": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).

    •  "v#.#": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).

    •  "v#.#.#": includes links to all released versions.

    •  "v^": includes a link to the docs for the maximum version (i.e. a link vX.Y pointing to vX.Y.Z for highest X, Y, Z, respectively).

    •  A pair, e.g. "first" => "second", which will put "first" in the selector, and generate a url from which "second" can be accessed. The second argument can be "v^", to point to
       the maximum version docs (as in e.g. "stable" => "v^").

The default should be versions = ["stable" => "v^", "v#.#", devurl => devurl] but maybe it's not? Anyway it's good to be explicit.

Also the default is devbranch = nothing, which isn't guaranteed to return main, so let's be explicit about that.

cc @navidcy

[tomchor]

Apparently Oceananigans does the same thing: https://github.com/CliMA/Oceananigans.jl/blob/main/docs/make.jl#L173-L179

Along with a force_push option that doesn't seem relevant here.

[tomchor]

@navidcy For future record, this option of deploydocs seems useful:

  branch_previews is the branch to which pull request previews are deployed. It defaults to the value of branch.

In particular, it would be good to set a different branch for previews and then cleaning up would be as easy as deleting that branch from the repo. Not sure if you wanna do this in Oceananigans but I'm thinking of trying this here.

[navidcy]

@navidcy For future record, this option of deploydocs seems useful:

  branch_previews is the branch to which pull request previews are deployed. It defaults to the value of branch.

In particular, it would be good to set a different branch for previews and then cleaning up would be as easy as deleting that branch from the repo. Not sure if you wanna do this in Oceananigans but I'm thinking of trying this here.

Yes! I was thinking to try this!

[tomchor]

Not only this didn't work, but now the docs for version v0.11.2 didn't even appear in the gh-pages branch: https://github.com/tomchor/Oceanostics.jl/tree/gh-pages

[navidcy]

damn...

[navidcy]

wait... it's there, no?

[tomchor]

Oh yeah, it turns out that I hadn't set up the ssh authentication keys properly. It's working as of a couple of hours ago! :tada:

[navidcy]

@navidcy For future record, this option of deploydocs seems useful:

  branch_previews is the branch to which pull request previews are deployed. It defaults to the value of branch.

In particular, it would be good to set a different branch for previews and then cleaning up would be as easy as deleting that branch from the repo. Not sure if you wanna do this in Oceananigans but I'm thinking of trying this here.

Yes! I was thinking to try this!

so I still don't understand how it works -- I tried to do with no much success.

if we deploy in the same repo as the docs but on a different branch then how will the website be deployed (the website is deployed based on one branch so it can't have access to both...)

if we deploy the previews on a different repo it might work, but can we do that?

[tomchor]

I think if we deploy them on a different preview-only branch, they won't got pushed to the website and instead we'll have to open them manually locally.

But imo that's still much easier than building locally and then opening locally.

But I'm not sure. I think I'll open a PR with this feature soon to test these things out. Feel free to open it yourself too if you wanna explore!