Replace set-default subcommand with a plugin option?

[jimporter]

To help keep the default-version redirect up to date (and possibly add support for nice 404 handling), it might make sense to remove the set-default subcommand and instead manage the redirect via the MkDocs plugin.

[nejch]

@jimporter this would be really nice to always change the default to the current deployed version from CI and just forget about set-default. It would also keep the gh-pages history cleaner if each deployment was just one commit.

What is the idea for the implementation here - something like below? Or am I misunderstanding this?

plugins:
  - mike:
      set_current_default: true

And then:

diff --git a/mike/commands.py b/mike/commands.py
index b762f1f..d569019 100644
--- a/mike/commands.py
+++ b/mike/commands.py
@@ -53,7 +53,7 @@ def make_nojekyll():
 @contextmanager
 def deploy(cfg, version, title=None, aliases=[], update_aliases=False,
            redirect=True, template=None, *, branch='gh-pages', message=None,
-           prefix=''):
+           prefix='', set_current_default=False):
     if message is None:
         message = (
             'Deployed {rev} to {doc_version}{prefix} with MkDocs ' +
@@ -94,6 +94,12 @@ def deploy(cfg, version, title=None, aliases=[], update_aliases=False,
                 else:
                     commit.add_file(alias_file)
 
+        if set_current_default:
+            commit.add_file(git_utils.FileInfo(
+                os.path.join(prefix, 'index.html'),
+                t.render(href=version + '/')
+            ))
+
         commit.add_file(versions_to_file_info(all_versions, prefix))
         commit.add_file(make_nojekyll())

Edit: ah, I see it's more likely you'll want a setting that'll give you something like latest/stable and sync that with aliases I guess.

[jimporter]

The API would be something more like a default_version property. Basically just putting the argument you'd pass to mike set-default into the config file.

That said, I'm still not 100% convinced that this is the right way to do things. In practice, mike is designed to be easy to call the various subcommands in a scriptable way; ensuring that you only need to call mike deploy isn't really the goal. For a real-world example of more-complex usage, see: https://github.com/jimporter/bfg9000/blob/28a61770e9c491ceecea6ba934ded3865a76f9e8/setup.py#L83-L103

[nejch]

Thanks for the quick reply. My main idea behind this was to work toward a clean way to do #25, and wanted to reduce pushes to other branches, so having a declarative way of doing things in a single step per build seemed like it would make sense (the current solutions in that issue involve some manual hacks which I think could be removed). Basically, it'd be great if all the steps, even if scripted, would be done before the changes are actually committed or deployed.

GitLab Pages was implemented much later than GitHub Pages, so it's less of a commit-based workflow and more CI/CD based - it deploys sites as artifacts explicitly from a CI/CD job, and it's mainly done from the default branch (as you would with other deployments). Pushing a lot of commits/builds to a git branch from that point of view is like abusing git for artifact storage (although I understand this is a core part of both GitHub Pages and mike, and very useful in this context to keep old reproducible builds). I'll move this discussion to the other issue, just wanted to give context.

Would having a --set-default-version as a flag for mike deploy also be an option as an alternative?

Slightly related: would it make sense to keep the default version in versions.json (e.g. "default": "true") and then not have to change the redirect template that reads from the json? I can open a separate issue if this makes sense to you.

[jimporter]

Thanks for the quick reply. My main idea behind this was to work toward a clean way to do #25, and wanted to reduce pushes to other branches, so having a declarative way of doing things in a single step per build seemed like it would make sense (the current solutions in that issue involve some manual hacks which I think could be removed).

There's really no declarative way to build all versions of the docs, so I don't think this would actually help handle #25. As you correctly mention elsewhere, mike relies completely on being able to keep around old build artifacts (read: generated docs) and to incrementally update them or add new versions of docs alongside. That's fundamentally the opposite of tooling that wants you to generate the full build artifact to deploy somewhere; the only way to reconcile the two would be to let mike work as it does now and then as the last step, generate the artifact-to-be-deployed by checking out the latest commit of gh-pages (or whatever your favorite branch name is).

Pushing a lot of commits/builds to a git branch from that point of view is like abusing git for artifact storage (although I understand this is a core part of both GitHub Pages and mike, and very useful in this context to keep old reproducible builds).

In a sense this is true; an "ideologically pure" ;) solution would involve having a proper webserver that hosts your build artifacts (docs, in this case) and knows what to do to let multiple versions live happily side by side. For a server hosting tarballs, this is pretty trivial (just push your artifact to a directory). For a server hosting docs, well... that's just Read the Docs.

More generally, mike was never intended to be the solution for (self-hosted) versioning of MkDocs docs, just a solution. The majority of the code is effectively just working around the fact that Github Pages is merely a dumb file server (e.g. instead of using Apache-like redirects, mike generates HTML redirects/copies for aliased versions). If you were using a smarter web server (or even just a different one), you wouldn't get nearly as much value out of mike. This gets somewhat confused because of mkdocs-material "officially" supporting mike for versioning; it would probably be more precise to say that mkdocs-material supports the "mike versioning metadata scheme" (i.e. versions.json).

Ultimately, for cases where mike itself isn't a clean fit, I'd encourage people to write new tools that fit that case better.

[ofek]

When is v2.0 expected?

[jimporter]

Probably not for a while. (Note: This feature isn't guaranteed to be a part of 2.0, and whether it gets added is mostly going to come down to whether I need it for 404 support.)

[nejch]

There's really no declarative way to build all versions of the docs, so I don't think this would actually help handle #25. As you correctly mention elsewhere, mike relies completely on being able to keep around old build artifacts (read: generated docs) and to incrementally update them or add new versions of docs alongside.

Sorry, didn't mean to build all versions, but to "build and set current version to default", I guess that was my idea. Perhaps that's not too important either. I realize the build would need to fetch the previously deployed artifacts for this. (I mean, I did toy with the idea of looping over the last few tags and checkout+build them - I'm sure that can be hacked together, as wasteful as that is 😁)

That's fundamentally the opposite of tooling that wants you to generate the full build artifact to deploy somewhere; the only way to reconcile the two would be to let mike work as it does now and then as the last step, generate the artifact-to-be-deployed by checking out the latest commit of gh-pages (or whatever your favorite branch name is).

Yes, that's actually sort of what I did in #25 (comment).

More generally, mike was never intended to be the solution for (self-hosted) versioning of MkDocs docs, just a solution. The majority of the code is effectively just working around the fact that Github Pages is merely a dumb file server (e.g. instead of using Apache-like redirects, mike generates HTML redirects/copies for aliased versions). If you were using a smarter web server (or even just a different one), you wouldn't get nearly as much value out of mike. This gets somewhat confused because of mkdocs-material "officially" supporting mike for versioning; it would probably be more precise to say that mkdocs-material supports the "mike versioning metadata scheme" (i.e. versions.json).

Ultimately, for cases where mike itself isn't a clean fit, I'd encourage people to write new tools that fit that case better.

Makes sense! Just thought trying to make it work upstream first might make sense, because in reality mike is the only maintained solution 🐱 and the mkdocs-material support does give it a lot more visibility even if it just establishes a scheme/convention. Anyway, #25 (comment) should give a reasonable solution for gitlab IMO, this is a little off-topic here now :)

[jimporter]

Would having a --set-default-version as a flag for mike deploy also be an option as an alternative?

I'm coming around to this idea, since it would fit in well alongside --update-aliases, and it makes intuitive sense to me: the mike section in mkdocs.yml is for settings that rarely/never change throughout the lifetime of a project, and the command line is for stuff that does change (e.g. the version you're deploying). Setting the default fits more closely in the latter bucket, I think.

That said, my personal recommendation is to set a latest alias, call mike set-default latest, and then update where the latest alias points to whenever you publish a new release. That means that search results should generally point to the latest version of the docs, and you never need to change the default again. That's probably worth documenting in the README.

[liangzhu2000]

That said, my personal recommendation is to set a latest alias, call mike set-default latest, and then update where the latest alias points to whenever you publish a new release. That means that search results should generally point to the latest version of the docs, and you never need to change the default again. That's probably worth documenting in the README.

Hi @jimporter, do we have to set the latest alias? It would be preferable to make it optional.

We have a use case which requires us to set up text versions like dev1 and dev2. The versions correspond to the respective feature branches. In this case, it is not like one version is newer than the other. They are just two tracks.

People think the following banner is quite confusing for our use case:
You're not viewing the latest version. Click here to go to latest.

[jimporter]

You don't need to set any version aliases if you don't want to.

However, that doesn't address your question about the banner. The banner actually comes from the mkdocs-material theme, so you should probably file an issue there to see what they can do about it. Maybe mike should add the ability to tag certain versions as "in development" to help mkdocs-material decide when to show the banner, but I'm not sure that's actually necessary.

This also ties in with #82 somewhat...

[jimporter]

Closing this issue, since I think #92 is a better way to handle the use cases described here.