I’d propose:
- ExDoc have an area to show links like hex does.
mix newadds the hex package url to links by default.
blatyo
Conduit Core Team
1
ericmj
Elixir Core Team
I have opened an issue for this on ex_doc [1]. We also want to add a version selector directly on the hexdocs page so you can jump between versions directly on hexdocs. These features are tricky to implement because hexdocs does not control the content it hosts, documentation is statically generated by ex_doc when the package is published and uploaded to hexdocs which only serves statically generated .html files via AWS S3. So we need to figure out a way to add dynamic content to ex_doc/hexdocs or fundamentally change how they work.
[1] Add links back to Hex package page and source repository · Issue #859 · elixir-lang/ex_doc · GitHub.
2
blatyo
Conduit Core Team
For the version selector, I could imagine hexdocs wrapping the ex_docs in an iframe. A nav element at the top or left provided by hexdocs could then allow you to select version.
1
NobbZ
Not an (i)frame… That will make make deeplinking problematic.
I’d strictly prefer some kind of injected JavaScript which provides an additional navbar.
And if we can not get this feature without giving up deep linking, I’d prefer having deeplinking rather than a link to other versions…
0
blatyo
Conduit Core Team
Deep linking could definitely work on initial render. However, if you’re click around in the iframe, I’m not aware of a good way to change the wrapping page’s URL. So, you’re probably right. Injecting JS may be better.
0
amnu3387
But switching between versions could just be a matter of links? ie. Kernel – Elixir v1.5.3
So if each version of the docs contained a list of previous versions and a way to pinpoint their url and the entry html page (or it could be retrievable by a get request for “versions”, it could work with the version number being a dropdown with the existing versions as links (and filtering out the current one)?
0
LostKobrakai
I kinda feel like people don’t really see that hexdocs is just plain static site hosting. It’s just by convention that most people use ex_doc for generation the documentation, but it could just as well be anything else. E.g. phoenix is hosting it’s js docs there as well: phoenix 1.8.8 | Documentation. On the other hand ex_doc is just a documentation library with no ties into hex. So both pieces of the puzzle currently don’t know anything of each other.
0
ericmj
Elixir Core Team
Previous versions would not be enough because then you could never switch to future versions. A GET request would work but that would mean an extra request for every page load.
Your example also shows why this is complicated because elixir is not a hex package so it would need to be handled in a special way. Today it is handled by the bob service GitHub - hexpm/bob: The Builder · GitHub so we would need to extend this somehow to the version selector.
0
ericmj
Elixir Core Team
You are making a good point. In one sense hexdocs is flexible because it’s simply static file hosting, which means every package can chose how to build their docs. Because of this we can host erlang, elixir, and javascript without any extra work. On the other hand it makes it very hard to extend hexdocs with new features, such as extra links, version selectors, full text search, and so on.
1
axelson
Scenic Core Team
Since this would be handled by Javascript anyway what if we don’t perform the GET until the user clicks on the version selector dropbown? Switching the docs version isn’t something that is done very often so I think that would be a reasonable tradeoff.
1