And does the build process of the docs have access to previous versions?
Because if it has (or if it could be made aware somehow during build), then it could also output a small json file as part of the static website, like versions.json, living on the root of the website, which would allow a small js script to request this file from the canonical url (latest version) and then build the dropdown. So a small js snippet could be injected in any version and request the canonical versions.js without having to have prior knowledge of the available versions?
amnu3387
1
ericmj
Elixir Core Team
We could fetch the list of previous versions from the API or repository. Bu that means we could only switch to previous versions, when hexdocs.pm/ecto/1.1.0 is created hexdocs.pm/ecto/1.0.0 would not be able to link to it. We could move the file to hexdocs.pm/ecto/versions.json when uploading to S3 but that means ex_doc has to understand the URL structure of hexdocs.pm and link to things outside of what it generates.
0
michalmuskala
What if ex_doc standardised on having a versions.json part inside of the package and hexdocs would update this file for all released versions when a new version is pushed?
2
amnu3387
So there’s no way to inject a JS snippet into all versions?
What I meant was that, you build the docs for the latest version to put them online, in this latest version build, it would also output a ~/versions.json file.
The latest docs are accessible through the non-versioned url right? Like if you go to hexdocs.pm/ecto it shows you the latest version. So if the snippet always retrieved the versions from hexdocs.pm/package/versions.json it would always be able to retrieve all existing versions (assuming on doc build we could return all of them)? In the latest version of the docs it could import directly the JSON file since it’s in the known directory, while the previous versions would use the snippet to retrieve it?
I’m really not familiar with how docs are built so this might not make sense at all/be overlooking something basic
0
voughtdq
ex_doc could include HTML “template comments”:
<!--EX_DOC_JS_INCLUDES-->
then during the build process, the builder can replace it with whatever necessary after ex_doc finishes. This way ex_doc doesn’t have to know anything and things like version selector can be added without too much trouble.
It’s not perfect, but I think it’s a nice trade off.
0
ericmj
Elixir Core Team
That would work but ex_doc would make an assumption about the url structure of where it’s going to be hosted. Keep in mind that today all links and references in ex_doc are relative, that means you can drop in the generated documentation in a web server that can host files from a filesystem and it just works anywhere.
The path to the versions file can be a config option that hex passes to ex_doc but it means we are forever tied to to the url structure we have now, for example we couldn’t later decide to move the docs to hex.pm/docs/phoenix/… without breaking existing documentation.
This is a compromise that might be worth to take but it’s important to keep in mind that we are making a change that can have consequences we don’t know of yet.
2