Hi @KristerV , I’m a long time user of devdocs.io and use it for Elixir, Erlang, Ruby and Python. I use it because works everywhere (web based) and works offline (if you download docsets in advance) and supports most of the languages I use. However, it’s by no means an ideal solution. There are a number of pain points with devdocs:
As you’ve discovered adding docs to devdocs is possible, but it’s not really well suited for libraries. Your tool provides a nice hierarchy so you can organize things into a tree. Whereas with devdocs there are really just three levels: the docset, the module/class, and the function/method. It’s not possible to do thinks like language > package > namespace > module > function.
devdocs being web based is good. But CLI is even better. I’m a maintainer of asdf and I’ve wanted a tool that could read asdf versions and provide docs for the current versions by default. CLI could be a big improvement because: a) a lot of us live on the CLI, and b) it’s easy for editors to build integration plugins for CLI tools (e.g. inline docs in vim, VS code, etc…)
The tooling around devdocs isn’t terrible, but it’s not great either. There are bugs/inconsistencies with the way Elixir and Erlang docs are handled. For example, it gets types confused with functions (devdocs doesn’t seem to have support for the distinction between the two) and it doesn’t handle the : module-function delimiter in Erlang.
Anyway, just wanted to chime in and say I think there is a lot of room for improvement in this area. While I’ll probably be sticking with devdocs for the time being it’s possible to build something better.
This thread inspired me to create a mix task which generates a single exdoc that includes docs for your app plus all of its dependencies (and nested deps) so you can simply browse and search them as if all your code and its dependencies were a monorepo: mix docs.deps (feel free to copy the code, improve, and share)
It includes the readme of each dep when one exists, but haven’t yet tried to include other guides. Also not sure how to include docs of Elixir itself.
Iirc this was brough up as well in the slack conversation preceeding this topic. I’ve looked a fair bit into it, but I’m not a big fan of how it needs to depend on the markup generated of ex_doc - a fact I’ll try to address in the future with my library. It’s also missing table of contents support and hiding layout. I didn’t try it, but I seem to recall it not working in it’s current state as well. Also there’s more to come from my side once I get around to implementing the ideas I have.
Yeah I didn’t mean to stop you! I used that repo in the past and it was quite broken (I submitted a big PR at the time, but not sure of its status since then)…
i’m actually using my created app daily and find it quite convenient, even without really prioritizing the search results properly. here’s a few annoyances i’ve fixed:
package list is now dynamic, so users can add what to index on the fly
input is autofocused on launch (such innovation, i know)
GitLab link added (omg not proud of this code at all but whatever)
index page has small intro so users aren’t confused immediately.
I was really confused when I search for Enum that I don’t get all the functions of the Enum module. For example, map is not in there. But when I search for map it does show up?
Is that the intended behaviour?
oh shoot, you’re right. i forgot. there’s a limit on how many funs it shows. my logic was that because there are many packages then ending up with 500 results isn’t exactly helpful.
i’d be happy to hear your usecase though. myself when i want to see all Enum functions i just click on Enum and hide the sidebar to see Hexdocs own menu.
I knew there was a function in enum but forgot the name. Typed enum, scanned the list of functions but couldn’t find it and was confused.
Hiding the sidebar was something I learned about right now when you said that that was possible. I should probably have seen it if I searched a bit more…
you know what? that’s a legit problem. such a simple tool shouldn’t create so much confusion. i’ve upped the limit of resuts to an insane 1000. that shouldn’t really be hit in this scenario, but if it does at least the UI wont halt.
i did something stupid. deleted a server that I didn’t use anymore. well guess what, hexdocs.krister.ee was running on it. well, I’ve restored the service, but the packages that are indexed have to be entered again. silly me.
The need for cross-package search arising from the conversation in this forum thread was one of the reasons for us to start building, so thank you all for the inspiration!
