Feedback on "version_json" and documentation

[Yura52]

Hi! I would like to share my experience of building a documentation website with a version dropdown. Here is a snapshot that works the way I want: https://github.com/Yura52/zero/tree/24f3d23f0d7d7a13bf549c8c1b8477fb15147f56

It took some time to make the version_json option work properly, because not everything was obvious to me from the documentation. Maybe my experience will be useful for others. Note that everything below is about version_json and NOT about version_info (I just don't have experience with the latter one).

1. In the section "Using a Javascript File" it is not clear what the text is referring to, I think the file that is supposed to be the illustration is missing.

2. The terminology of "relative" and "absolute" paths is confusing to me. Now I know that "relative path" means "any path including those starting with '/'" and "absolute" means a fully-functioning link. For example, "/zero/" and "zero" are "relative" paths and "https://yura52.github.io/zero/" is an "absolute" path. The former is the only option that can be used in version_json, the version_info option can use both.

3. Now, the most interesting part. In the case of version_json "relative path" means "relative to the parent location". In my case, I wanted my documentation for the project "Zero" to be served by GitHub Pages, so the link to the root of documentation was https://yura52.github.io/zero. I wanted the documentation for the stable version to be located in this root location and other versions to be located in subdirectories (for example, the version 1.2.3 should be located at https://yura52.github.io/zero/1.2.3). In the example above the dropdown offers two versions: "stable" and "dev" (the subdirectory 0.0.3 is saved for my personal convenience, it does not affect the website and can be removed). Now, _static/versions.json should contain paths relative to https://yura52.github.io and dev/_static/versions.json should contains paths relative to https://yura52.github.io/zero.

4. If the previous point is true, then the _static/versions.json file of the demo website is not valid. Since the version_info option is also used, the mistake does not affect anything.

5. It seems that the version_json option cannot be tested locally, "Other Versions Not Found" will be displayed instead of the version dropdown. So the website mentioned in the beginning will work properly only when deployed (for example, to GitHub Pages).