Small confusion regarding default branches

[Andre601]

I'm a bit confused right now regarding the set-default sub command and how it exactly is used.

Right now, I have a workflow set up which in order does the following on push:

• Checkout repository with a fetch-depth of 0
• Setup python 3.7
• Install Mike and Mkdocs-material
• Setup a Git User
• Run mike deploy dev followed by mike set-default dev --push

When I now check the deployed page does MkDocs material show the "outdated" banner, which usually only shows on outdated pages, while the page in question is dev Do I need to do anything different here or is the above setup the right one?

[jimporter]

Do you have a link to your repository and the commits where you tried to get this working? It's hard to diagnose these sorts of problems without seeing what actually happened.

• Checkout repository with a fetch-depth of 0

This is discussed in the README, but you want to be sure to get at least the latest commit from your docs branch, e.g. by calling git fetch origin gh-pages --depth=1. Otherwise, when mike generates the new commit for the gh-pages branch, it won't be based on your previous work, and then you won't be able to push.

• Run mike deploy dev followed by mike set-default dev --push

Setting the default is (generally) a one-time thing that you should run manually when setting up your project. There's no need to run it on every commit (though there's also no real harm in doing so).

[Andre601]

The repo is https://github.com/Andre601/AdvancedServerList and the site is hosted on a gh-pages branch.

Site itself is accessible at https://andre601.ch/AdvancedServerList

[jimporter]

Ok, I see what you mean now. I believe part of the issue is that due to the way Python[1] sorts versions: dev is considered "older" than any of your normal, numbered versions. I fixed that in https://github.com/jimporter/mike/issues/124, which is available on the latest development build of mike.

However, I'm not sure that will actually solve your problem. I don't know how exactly the Material theme handles the "outdated" banner, but the way I would expect it to work is that you'd have two kinds of banners: one for old releases (this is the current banner), and another kind of banner for dev builds (it would say something like, "This documentation is for a pre-release; click [here] to see the latest release's documentation.") The way I'd imagine this working is that the Material theme could recognize prerelease version identifiers, and then exclude them from the "is this outdated?" check. It'd probably be best to check with the Material theme maintainer on this one though, since I only have a limited understanding of all that code.

[1]: Well, it's really the verspec package, which I maintain now, but that's just copied from the more-official packaging package. (They removed LooseVersion support, which I relied on, so I forked that part of the code. Long story.)

[Andre601]

Ok, I see what you mean now. I believe part of the issue is that due to the way Python[1] sorts versions: dev is considered "older" than any of your normal, numbered versions. I fixed that in #124, which is available on the latest development build of mike.

I'm not used to pip that much, so I'm not sure how I would access this dev version exactly. Would I use that git+<url>@<version> format (I recall this being the format to use?) and supply a commit as the version, or is there a different aproach?

However, I'm not sure that will actually solve your problem. I don't know how exactly the Material theme handles the "outdated" banner, but the way I would expect it to work is that you'd have two kinds of banners: one for old releases (this is the current banner), and another kind of banner for dev builds (it would say something like, "This documentation is for a pre-release; click [here] to see the latest release's documentation.") The way I'd imagine this working is that the Material theme could recognize prerelease version identifiers, and then exclude them from the "is this outdated?" check. It'd probably be best to check with the Material theme maintainer on this one though, since I only have a limited understanding of all that code.

What I found is, that through its usage of jinja2, mkdocs-material is doing a self.isOutdated() check in its base.html file and if that is true include some aside block with a customizable outdated block. I have no idea what self exactly is here (I assume it's part of MkDocs?) as I can't find any location in the html file where it would be defined.

I would love a separate banner for the dev build ones, tho I imagine this being a lot more complicated to figure out here... Like how to know this branch is dev and not latest or older?

Also, given your statements regarding the maintainership of this project, I think it's not worth suggesting extra features like a command to define branches as dev (i.e. mike deploy --dev-branch dev or something along those lines), and instead look out for someone to eventually make a fork or separate version with changes implemented. It's a bit sad that you're not considering stuff that has no main benefit towards you, but that's kind of the curse of open source projects unfortunately and I can't blame you for not wanting to maintain stuff you see no benefit yourself in...

Tho, if I can ask for anything, I would request a --default option usable in the different commands, which does what set-default would do. It would allow more simple aproaches like mike deploy --push --default --update-aliases ${{ github.event.release.tag_name }} latest to always update default branch to latest release when published (I would probably scrap the entire dev branch in favour of only release branches here, so this would be a great beneficial feature for me).

[Andre601]

Also, right now I face another smaller issue where git is giving me an error, yelling that branches aren't up-to-date it seems? This now happened after I changed the fetch-depth in actions/checkout from 0 to 1.

I find it a bit confusing as to why this happens since checkout does create an empty repo, set remote and then fetch the repo from remote, so it should by all means be the latest data? Could this be related to Mike? Would I need to set the fetch-depth there too?

The workflow run in question (If you can understand the logs... I can't): https://github.com/Andre601/AdvancedServerList/actions/runs/4309288386/jobs/7516507710

The Workflow file: https://github.com/Andre601/AdvancedServerList/actions/runs/4309288386/workflow

(I used workflow_dispatch from the master branch)

[jimporter]

I'm not used to pip that much, so I'm not sure how I would access this dev version exactly. Would I use that git+<url>@<version> format (I recall this being the format to use?) and supply a commit as the version, or is there a different aproach?

I believe you just need this: pip install git+https://github.com/jimporter/mike.git. You can also add @<some-ref> if you want to specify the exact Git ref to install. That said, I'm not sure this will solve your immediate issue.

What I found is, that through its usage of jinja2, mkdocs-material is doing a self.isOutdated() check in its base.html file and if that is true include some aside block with a customizable outdated block. I have no idea what self exactly is here (I assume it's part of MkDocs?) as I can't find any location in the html file where it would be defined.

I would love a separate banner for the dev build ones, tho I imagine this being a lot more complicated to figure out here... Like how to know this branch is dev and not latest or older?

This would probably be up to the Material theme, but it could be as simple as Material letting you specify a list of development versions in your mkdocs.yml configuration.

Also, given your statements regarding the maintainership of this project, I think it's not worth suggesting extra features like a command to define branches as dev (i.e. mike deploy --dev-branch dev or something along those lines)

I think that makes sense actually. While the feature set for mike is pretty much defined now, I don't have an issue adding narrowly-scoped new features to the list.

It's a bit sad that you're not considering stuff that has no main benefit towards you, but that's kind of the curse of open source projects unfortunately and I can't blame you for not wanting to maintain stuff you see no benefit yourself in...

To be honest, if I were only adding features that directly benefit me, this project would have no commits after the release of v0.6-ish. Pretty much everything since then has been of little use to me. At this point though, my goal is to start shepherding this project into the "done" column. Ultimately, this means making sure that mike provides the necessary foundation to support various schemes for documentation, but in a way where I can give users the tools they need to do this without adding a lot of extra maintenance burden.

Tho, if I can ask for anything, I would request a --default option usable in the different commands, which does what set-default would do. It would allow more simple aproaches like mike deploy --push --default --update-aliases ${{ github.event.release.tag_name }} latest to always update default branch to latest release when published (I would probably scrap the entire dev branch in favour of only release branches here, so this would be a great beneficial feature for me).

The way I'd recommend doing this is:

# Do this once when setting up your docs:
mike set-default latest

# Do this each time you want to update your docs:
mike deploy --update-aliases <some-version> latest

I think adding a --default flag to deploy would be more confusing than having a separate set-default subcommand though: since deploy lets you specify multiple aliases (and it also updates any existing aliases for that version), it's less clear what --default should do in all case. For example, if the current default is one of the aliases you're updating, should --default do nothing? Change the default to the primary version? With the separate set-default subcommand, you can make this explicit.

Of course, there's nothing wrong with you running mike set-default explicitly. If it doesn't change anything, it shouldn't create a new commit (if it does, that's a bug).

[jimporter]

Also, right now I face another smaller issue where git is giving me an error, yelling that branches aren't up-to-date it seems? This now happened after I changed the fetch-depth in actions/checkout from 0 to 1.

I may have led you astray above; sorry about that. If you fetch with a depth of 1 that means it'll only fetch the latest commit on your default branch. Then, you'll also need to explicitly fetch your docs branch: for example, git fetch origin gh-pages --depth=1. That's more efficient than a fetch-depth of 0 on your repo because now you only need to fetch 2 commits - one for your default branch and one for gh-pages. However, it's also more typing in your CI script. Really, it's up to you which you choose; if a fetch-depth of 0 is working, then no need to change it.

(Initially, I had thought the issue you were having was related to an incorrect fetch-depth setting, which is why I mentioned it. But I think your prior config is fine, so long as you're not frustrated by slowness in your CI pipeline.)

[Andre601]

This would probably be up to the Material theme, but it could be as simple as Material letting you specify a list of development versions in your mkdocs.yml configuration.

Tagging @squidfunk here real quick, as he should know best what could be a good implementation for a "dev builds" solution... Tho, I think it should be relatively easy. (In fact, I could probs override the template myself to manually insert something to make that work, tho my experience with jinja2 is very limited)

[Andre601]

Also, I tried the git aproach with the Mike version, but as you assumed has this not fixed the issue. Site still defaults to dev (Which makes sense as I define it as default in the workflow run) but is treated as "outdated".

[squidfunk]

I haven't read the entire conversation, but you know that you can specify multiple versions that are considered stable, right? For all of the branches listed under default, the version warning will not be shown.

extra:
  version:
    default:
      - stable
      - development

Click on the code annotation to see this in the docs (we're working on allowing to deep link arbitrarily nested content)

[jimporter]

Click on the code annotation to see this in the docs (we're working on allowing to deep link arbitrarily nested content)

Cool, based on my understanding, this should resolve the issue here.

One note for the future though, @squidfunk: for mike 2.0, I'm planning on adding support for arbitrary user-defined properties associated with each version. For example, you might mark your development versions with {"development": true}. The idea is that mike will make it easy to set these properties, but otherwise won't pay attention to them; then other tools (e.g. the Material theme) could consult these properties to do whatever makes sense. In this case, Material could consult these properties and use that to decide when to show a banner. (This should hopefully also make it easier for other themes/tools to work with this info in a more-standardized way.)

[squidfunk]

Sounds great! Feel free to ping me if you have a prototype, happy to test it.

[Andre601]

I haven't read the entire conversation, but you know that you can specify multiple versions that are considered stable, right? For all of the branches listed under default, the version warning will not be shown.

extra:
  version:
    default:
      - stable
      - development

Click on the code annotation to see this in the docs (we're working on allowing to deep link arbitrarily nested content)

Not sure why I didn't see that section on the page... Guess I was tired at that time. 😅

Either way, I think I can close this issue now.