Proposal: Add shortcut for switching to other docs on hexdocs.pm

[cybrox]

My biggest annoyance when using hexdocs while working is switching between different project's documentations. I usually solve this by keeping multiple tabs open and having bookmarks for the documentations that I often use. So I was thinking if there isn't an easier way for solving this.

To keep things short, my proposal here would be to:

• Make the docs aware as to wether or not they are viewed via hexdocs or not (using window.location.hostname for example)
• If we are viewing the published documentation, a new keyboard shortcut g is added for "going to" another documentation
• Pressing g opens a modal with a search field (like the shortcut help modal), where the name of another project can be entered (e.g. ecto) and hitting enter will redirect to hexdocs.pm/<project>

This is very bare-bones and I wrote a patch to do this in 5 minutes, but I didn't want to PR it yet, because I wanted to get feedback on the proposal first. - Also, I did search GH issues and didn't find anything but maybe a similar proposal was around already?

Ok, for improving usability of this feature a bit:

• The search input in the goto modal could feature autocomplete, although neither hex nor hexdocs currently do this for their search fields. (I assume for traffic reasons?)
• The search input could also support linking to a module directly, by using a syntax like projectname.module (e.g. plug.conn)

What bugs me a bit about adding this to ex_doc:

• It is useless in ex_doc itself, ideally, this would be injected by hexdocs when rendering the docs but as far as I can see, this is currently not done with anything, the docs are just fetched from a bucket and displayed as they are.

Does anyone else think this would be useful or am I off track with this one? :)

[josevalim]

I agree with the description of the problem. Regarding having a feature that does not work on ExDoc by itself, we alresdy have a similar feature via the versions drop down. The way it works is that there is a docs_config.js file which sets some variables that enables it. Hex defined a docs_config.js automatically when you deploy your docs. I can see a similar feature working for a “go to project” or “go to page”, however, with more than 8500 packages, we cannot simply list all of them. So we would need a similar feature to autocomplete, which requires an API from . Also, if we want to link to a particular module/page in a given project, then Hex needs to index it. So perhaps the next step here is to bring the discussion to the Hex team and see which APIs they want to expose for auto completing docs. Another approach, which won’t require so much interoperability with Hexdocs, is to allow users to automatically list projects deps they want to have have links to. For example, when Phoenix is published, it could say it would like to also include Ecto modules in its autocomplete or a similar feature. The downside is that this only works with pre-determined deps.

…

-- *José Valim* www.plataformatec.com.br Skype: jv.ptec Founder and Director of R&D

[cybrox]

Oh, I didn't know about docs_config.js. In that case, it would definitely make sense to use that.

So perhaps the next step here is to bring the discussion to the Hex team
and see which APIs they want to expose for auto completing docs.

For implementing this proplery (with autocomplete for projects and modules), there would definitely be hex APIs required, so I think this is the way to go.

Another approach, which won’t require so much interoperability with
Hexdocs, is to allow users to automatically list projects deps they want to
have have links to. For example, when Phoenix is published, it could say it
would like to also include Ecto modules in its autocomplete or a similar
feature. The downside is that this only works with pre-determined deps.

I see the idea here but I think it would be a bit of a hassle both for authors writing the docs and users viewing the docs on hexdocs. As you said, authors would have to add information manually and I think it might be confusing to users, e.g. why can I switch from phoenix to plug but not to bodyguard, which is an equally valid request from the user side but it wouldn't make sense for phoenix to keep a list of all phoenix related packages up-to-date.

[josevalim]

Hi @cybrox, any progress in this front? Were you able to start a discussion with the Hex team? Thanks!

[cybrox]

Hi @josevalim sorry for the late reply, haven't gotten around to it, since I was on holidays. I'll inquire about possible solutions this week.

[wojtekmach]

Also, if we want to link to a particular module/page in a given
project, then Hex needs to index it.

@josevalim are you thinking about displaying package search results in the existing ex_doc autocomplete box? Indexing all of that data aside, I think it might be tricky to come up with relevant search results. That being said, if you know what you're searching for, I must say that it would be incredibly cool to be able to autocomplete things like Enum.map, mix release, Ecto.Changeset and seamlessly switch between them.

If we focus on just dedicated package search modal I think we have pretty much all the pieces we need. We already have a basic search with autocomplete on https://hexdocs.pm homepage, it's sending an Ajax request to https://hexdocs.pm/sitemap.xml so that could be our source. If we could later "backport" ExDoc autocomplete look and feel to hexdocs homepage that would be fantastic.

I like the idea of having keyboard shortcuts for these, perhaps:

g v - focus version switcher

g p - opens up a modal with package search

[josevalim]

The sitemap is 1.2MB and it will likely only get larger. I think we would need autocomplete on the Hex side, at least as a starting point.

[cybrox]

That being said, if you know what you're searching for, I must say that it would be incredibly cool to be able to autocomplete things like Enum.map, mix release, Ecto.Changeset and seamlessly switch between them.

This would indeed be awesone, however, I would still keep it separate from the existing ex_doc autocomplete box. I think it makes sense that the default search only searches the current documentation, otherwise, some confusing situations could arise with similar naming or mix tasks or modules. - But it is a very interesting idea for the future of this "quick switch" idea.

---

As for the sitemap, I have some issues with it. First, it will be cached by the browser, so its behaviour is inconsistent for different users. If it is not cached, it takes very long to load, since as José said, it's growing rather fast. It would work as a proof of concept but for being actually usable, I think autocomplete results from Hex would definitely be better.

Thanks for the input @wojtekmach, I'll also ping @ericmj here real quick, since I think you two would most likely have to decide wether or not this would be an option, right?

[michalmuskala]

My understanding is that the primary reason for cross-package search is to discover functions you can call from inside a project. If that's the case - why not use the information provided by the project to discover & index the documentation? In particular, I'm thinking of a mix task that would download & index documentation for all packages available in the project and exposed them in a unified interface. This could have an additional advantage of using correct versions of all the packages.

Alternatively, there could be a hexdocs endpoint that would accept a description of the versions and compute & cache that creating a sort of a workspace for you in the browser.

[cybrox]

@michalmuskala Thanks for the input! I think we'd have to split the discussion between package switching and fully fledged cross-package search. The original problem I'd want to solve with this issue is just getting from package A to package B quick, I think with all the good ideas, we are now discussing three separate enhancements that could be tackled one after the other.

1. I want to just switch to another project. The workflow I imagine here i, assuming I'm on any hexdocs doc: press g, type "ecto ↵", press s, type "Ecto.Query ↵" -> I'm now at the docs for Ecto.Query. Quite fast. This would only require a solution like the sitemap, or ideally, a queryable API from hex. (Assuming this is implemented on the hex side, I think it could also improve the search on hex.pm and hexdocs.pm)

2. I want my package switch suggestions to be reasonable. We could use the project's dependencies listed in its mixfile to determine which packages are more important to link to and which versions to link to. As you said, I guess this would best be done by a mix task.

3. We could merge the two steps the user performs in 1. into one, which is essentially what you described. Type Ecto.Query in any packages quick-switch modal and you're there immediately.

I think it might be easiest to solve 1. first and see if there's any interesting positive or negative feedback.

[ericmj]

What kind of API are you looking for to do the autocomplete? Today we have: https://hex.pm/api/packages?search=name:phoen*. It returns some unnecessary data so in the future we can optimize it to only return the name fields if you add &fields=name to the query.

[ericmj]

1. What kind of API are you looking for to do the autocomplete? Today we have: https://hex.pm/api/packages?search=name:phoen*. It returns some extra data you won't need but we can add a query to limit the fields in the future.

2. This could be generated by ex_doc which the autocomplete script can pull from before hitting the API. Alternatively we could include it when we build docs_config.js.

3. This is harder to do because it requires a complete index of all modules and functions in all Hex packages. ex_doc could generate it but it means you can only search in your dependencies and the index would not be up to date.