Ex_doc: A dropdown for selecting package version

[jegaxd26]

Currently if I want to read documentation for some specific version of a package I have to manually edit the url.I think it would be nice if we had a dropdown where it currently shows the version to select the desired one. I can take this one if you guys think that it makes sense

[josevalim]

Hi @jegaxd26, this would have to be coordinated with the Hex team, because ExDoc itself does know anything about hosting and where the other versions may be. A very simple idea is for hex to store a versions.json file and we configure ex_doc to use this file.

[michallepicki]

Related discussion: https://github.com/hexpm/hexpm/issues/682

[michallepicki]

I have a WIP here
I published the rendered example here

I need to delay opening the select to after it is populated with options (I get a popup with no options when opening for the first time on my mobile), I know styling may need a few fixes, but other than that and naming - what do you think about this approach?

edit: the example .js file used in the above example is here

[josevalim]

I added this so that we can get redirected to the exact page (for example, a module) and anchor (for example, a function) for chosen package version.

Oh, I see. This wouldn't work if we use the dropdown to also have other links, like to the Hex package source. But it is unclear if people actually want to do that. In any case, for now I would go with the simplest approach possible, which is to link to the root. :)

For the other points, I will make sure to get @ericmj's feedback.

[michallepicki]

Right, if we want to have other information loaded through this .js file, we have more reasons to fetch it always instead of lazily. I'm not sure if we want other links than versions to be present in this particular dropdown, though.

[josevalim]

So I talked to Eric and we agree that always including the script tag is
better and simpler. The only question is what happens when the file is not
there... it will be a 404. But does that manifest itself as an errors for
users? If so, it may be better to generate an empty .js file in there (if
none is available)?

The other part is to show the drop down only if there is something to
select. Is that easily doable? The other thing is to mark the current
version as selected if it appears in the list.

Thanks for pushing this forward, really appreciated!

José Valimwww.plataformatec.com.br
http://www.plataformatec.com.br/Founder and Director of R&D

[michallepicki]

I have a new WIP version, adressed comments and added sidebar footer links:

• Code diff
• Example - you can switch between 6.6.6 and 4.2.0 back and forth.
• script - I inlined one of the icons

The only question is what happens when the file is not there... it will be a 404. But does that manifest itself as an errors for users? If so, it may be better to generate an empty .js file in there (if none is available)?

This will look as if additional script was not provided, so exactly the same as before (text instead of select). Example here

[michallepicki]

@josevalim I went with your suggestion and the current version is selected but I think we can go as far as making it disabled so it doesn't show up in the options.

Also for now I simplified navigating to the other doc version and removed this but with the new sidebar footer links placement, what do you think about bringing it back?

[josevalim]

I have a new WIP version, addressed comments and added sidebar footer links:

This looks great! :heart: Just a minor nitpick: can we keep the arrow pointing down outside of the select option?

This will look as if additional script was not provided, so exactly the same as before (text instead of select). Example here

Right, so console.log says "Failed to load resource: the server responded with a status of 404 ()". Is this an issue?

what do you think about bringing it back?

I don't think we should go with the links on the sidebar footer for now. So I would first push the simplest version of the dropdown, collect feedback about using it as a general link structure and then specialize accordingly.

[michallepicki]

can we keep the arrow pointing down outside of the select option?

I think so, yes, I haven't yet figured out a way to do it so the arrow stays clickable but it's certainly possible - in the worst case with a bit of javascript. If we make the chosen option disabled it's not a problem but I guess having it present in the dropdown/popup is also useful.

console says "Failed to load resource: the server responded with a status of 404 ()". Is this an issue?

AFAIK not really but we'll have to test all browsers and online/offline.

I would first push the simplest version of the dropdown, collect feedback about using it as a general link structure and then specialize accordingly.

OK, that's fine. I'm just worried people will start using the dropdown as a way to link to other sites like hex.pm and then us introducing page linking would break things for them. So I think we'll have to make sure to document this feature well saying it's strictly for linking to other versions documentation.

[josevalim]

I think so, yes, I haven't yet figured out a way to do it so the arrow stays clickable but it's certainly possible - in the worst case with a bit of javascript.

You know what, now that I think about it, it is fine as is because it also works as indicator of the current version. Disabling it also sounds good.

So I think we'll have to make sure to document this feature well saying it's strictly for linking to other versions documentation.

But that's exactly what I don't want to restrict right now. :) If we want to keep the hashes, maybe we can use a new attribute in the JS object to specify it, like keep_hash: true and then we know precisely when to keep it but we don't have to worry about it for now.

[josevalim]

Three minor nitpicks in the implementation:

1. about the variable name, what if we call it versionNodes to mirror the sidebarNodes?

2. about the shared_script configuration, I am not sure what is the best way to go. That's because we want it to work with Hex out of the box, so we need to provide a default... but providing a default means it will return a 404 unless people disable it? Also, maybe a better name would be javascript_script_path for clarity?

3. let's remove the sidebar footer links for now :)

[michallepicki]

So I think we'll have to make sure to document this feature well saying it's strictly for linking to other versions documentation.

But that's exactly what I don't want to restrict right now. :) If we want to keep the hashes, maybe we can use a new attribute in the JS object to specify it, like keep_hash: true and then we know precisely when to keep it but we don't have to worry about it for now.

I'm a bit confused. You don't want a separate feature for this yet but you want to allow users linking to non-documentation websites from the versions dropdown? To me it seems like two separate concerns (both ui-wise and code-wise) but you're right, we can modify our data structure to distinguish documentation and non-doc links...

a new attribute in the JS object to specify it, like keep_hash: true and then we know precisely when to keep it but we don't have to worry about it for now.

Is it just about the hash though? We also have the file name/path. Preserving the context will be a difficult problem to solve because we don't know what will change yet. I think a clear separation between link types won't hurt and it can make it easier for us in the future to eventually implement it. That's why I wanted to have different kind of links separate even now.

[josevalim]

I'm a bit confused. You don't want a separate feature for this yet but you want to allow users linking to non-documentation websites from the versions dropdown?

It is an option that has been discussed so we would like to try it before we knock it.

Is it just about the hash though? We also have the file name/path.

Right, we can adjust the name accordingly then.

[michallepicki]

I moved the arrow to a pseudo-element, removed the footer links and added preserve_path option:
diff
demo - will preserve path when switching to recent but not when switching to 0.0.0
shared_script.js

I think the preserve_path boolean gives us too little information to make it future-proof. Imagine we change the ex_doc path structure, we'd have to introduce a new preserve_path2 boolean to have this feature working when switching between docs using old path structure, have it disabled when switching from old to new and from new to old, and have it enabled when switching between new docs.

An example solution would be something like path_compatibility: {min: '0.0.0', max: '0.4.0'} so that we could always decide whether we can preserve path or not. But I'll think about it a bit more.

[josevalim]

Fantastic! I think there are two remaining changes and then we can move to a PR and merge it:

1. Let's drop the preserve_path for now since the functionality itself has downsides. For example, modules that are added in later versions will return a 404 on future versions and I think some folks will interpret those as bugs. I really want to ship something without path preservation and collect feedback before we add it. :)

2. I am not sure about the name "shared_script_path". Why is it shared? Which kind of script is it? For example, it could be an Elixir script. In theory, it is just a javascript file and you could do whatever you want in there. It just happens that you are setting some variables to be used by ExDoc but that's not all. Thoughts?