JSON format coordination with mike

[larsoner]

Mike supports version switchers and so does pydata-sphinx-theme. It would be nice to coordinate a bit on the format, especially as I'm looking into making a mike-for-sphinx sort of project. I got a conversation going over in jimporter/mike#263 -- the fields at stake are basically name vs title, making url optional (with relative resolution as the default), and whether the theme could understand mike's aliases (and mike our preferred). Related here are at least #786 and #2465. Would love to have pydata-sphinx-theme maintainer opinions over in the mike issue! I'll talk to @drammock about this directly as well soon 😄

[jimporter]

Hi, I'm the developer for mike. Just a few quick thoughts:

• For Make our versions.json support a top-level dictionary instead of just a list #786, while I've had the same thought that a top-level dictionary for versions.json would have made a few things easier, I don't think it's strictly necessary (for how mike does things, anyway). I'm particularly leery of the idea that this would be "to configure behavior changes for the switcher across all versions of documentation". In an ideal world, a given version of the docs could have been generated with any version of any framework (mike/MkDocs, pydata-sphinx-theme/Sphinx, etc), so the configuration really should be version-specific.
• The naming of name (here) vs title (mike) is a little tricky to resolve cleanly. In mike, I designed things so that generated docs are a build artifact that should never have to change after you make a release, so old versions of mike-powered docs would only recognize title. For compatibility, we could just include both. On the other hand, it's easy enough to migrate old docs to a new keyword, so maybe it's worth making the change and issuing a warning. (I'm biased, so I like title, but it's not a hard requirement for me.)
• I'm not sure if this project cares about version aliases. In mike, they're just used for redirecting from example.com/latest to example.com/1.0 (for example). That way, you can use permalinks to the latest version of the docs.