Version aliases usage

[mhostetter]

Are the version aliases functional in Sphinx Immaterial? I think some extra code or HTML is required, but since that is not my forte I may be mistaken.

From Material for Mkdocs' documentation and Sphinx Immaterial's documentation, my understanding is:

• To make multiple folders with different versions, docs/build/v1/ and docs/build/v2/ in my example.
• Add this to conf.py:

  html_theme_options = {
  "version_dropdown": True,
  "version_json": "../versions.json",
  }

• Add the versions JSON file at the same level as the folders, docs/build/versions.json in my example.

  [
  {
      "version": "v2",
      "title": "v2",
      "aliases": ["latest"]
  },
  {
      "version": "v1",
      "title": "v1",
      "aliases": []
  }
  ]

• Serve the docs/build/ folder from a webserver.

foo-190.zip

I can access http://localhost:8080/v1/ and http://localhost:8080/v2/, but http://localhost:8080/latest/ returns 404. I was expecting it to return the same content as http://localhost:8080/v2/ or simply redirect to http://localhost:8080/v2/. Am I misunderstanding how the feature works?

It seems there may need to be a special docs/build/index.html or something like a docs/build/latest -> docs/build/v1 symlink.

[2bndy5]

There were some changes from upstream recently (see this diff). Was aliases working before that (v0.9.1)?

I'm not sure, but I wouldn't expect that manually entering the URL with the alias would redirect without some file next to version.json designed to intercept/redirect. Looking at the JS, it seems to be mostly focused on working from events emitted by the version selector. Its possible the mike plugin that upstream uses does some extra work for aliases - work that the upstream theme's JS need not implement.

[mhostetter]

I was never able to get aliases to work.

Its possible the mike plugin that upstream uses does some extra work for aliases - work that the upstream theme's JS need not implement.

I do think Mike is doing some work behind the scenes. Also, see here.

[2bndy5]

It would be nice if we could support using sphinxcontrib-versioning similar to how upstream uses mike. Although, I don't think that ext supports aliasing a version's docs.

For now, I think the only extent that the aliases can provide is an alternative name in the version selector, but that doesn't seem too comprehensive if the underlying URL can't use the alias.

[mhostetter]

I was able to get the alias to work by creating a symlink during documentation build/publish (from v0.1.2 to latest in my project). https://github.com/mhostetter/galois/commit/7f5923100c190f2352696324b6bf66643f405c40

This works as I intend -- <url>/latest/* displays the same contents as <url>/v0.1.2/*. See here: https://mhostetter.github.io/galois/latest/.

I don't believe Material for Mkdocs is using aliases in versions.json at all. I think only mike uses it. For example, my version dropdown doesn't change, even when specifying aliases.

[2bndy5]

That's interesting, but I don't know how that would/could be integrated with the theme. I imagine we could create a html template that gets rendered along side the version.json file's path, and let the rendered template create/update the needed redirect files.

BTW, github has a python option for steps' shell field. It could be used to execute python code in a REPL without relying on an action.

[2bndy5]

Let's not forget about the version warning banner we inherited from upstream.

[jbms]

The purpose of aliases is to allow you to access the docs using a URL like /latest/ and have the version selector display 2.3 or whatever. The version mechanism isn't a complete versioning system --- you still need to implement your own version management. For the aliases you do need to separately create a symlink or routing rule on the webserver.

[jbms]

We should clarify this in the documentation.

[2bndy5]

yeah, the template idea did seem outside the scope of the theme itself. The docs could use some embellishment on this topic.

[mhostetter]

I don't know how that would/could be integrated with the theme.

Yeah, I agree. I was thinking we should just change the docs to make it clear what a user must independently do to make the aliases work.

BTW, github has a python option for steps' shell field. It could be used to execute python code in a REPL without relying on an action.

@2bndy5 that's handy, thanks for the tip!

Let's not forget about the version warning banner we inherited from upstream.

Yeah. I'm trying to get that working now....

[2bndy5]

Let's not forget about the version warning banner we inherited from upstream.

Yeah. I'm trying to get that working now....

Cool! Let us know your findings so they can be included in the docs' revision.

[mhostetter]

Following this suggestion, I was able to get the version banner to work by:

• Adding this docs/_templates/base.html

  
  {% extends "!base.html" %}

{% block outdated %} You're not viewing the latest version. Click here to go to latest. {% endblock %}

- Add this `index.html` as the same level as `versions.json`.
```html
<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="refresh" content="0; url=latest/" />
        <link rel="canonical" href="latest/" />
    </head>
</html>

Demo here: https://mhostetter.github.io/galois/v0.1.1/getting-started/

[2bndy5]

Awesome, thanks for the testing and feedback! I remember why we didn't choose the indigo as our docs' primary color; it makes the links hard to read (low contrast). In the case of the version banner warning when using the dark scheme, it looks like the indigo background color is too similar to the hyperlink color.

To override the default color of the banner, you can use the CSS

/* only override for dark/slate scheme; color is acceptable in light/default scheme */
[data-md-color-scheme="slate"] .md-banner--warning {
  background: var(--md-footer-bg-color);
}

This should force the use of the footer color, but of course you can set it to whatever.

---

As for the redirect page, some browsers may not respect the <meta http-equiv="refresh", so typically it is pretty common to also inform the user that a redirect to a page should've occurred. I would suggest adding

    </head>
    <body>
        <p>If this page does not refresh automatically, then please direct your browser to
            <a href="latest/">our latest docs</a>.
        </p>
    </body>
</html>

[mhostetter]

In the case of the version banner warning when using the dark scheme, it looks like the indigo background color is too similar to the hyperlink color.

I thought the same. Thanks for the CSS tip on how to override!

As for the redirect page, some browsers may not respect the <meta http-equiv="refresh", so typically it is pretty common to also inform the user that a redirect to a page should've occurred.

Another good tip, thanks!