hexpm
WIP: mix hex.docs.search task
Hey folks! This is an initial foray into defininga mix task for searching hex docs. It does the bare minimum right now, but gives us a starting point for discussion. Things to discuss likely include:
- Should this be a thing at all?
- Should we present human readable output? If so, how do you want to go about handling JSON, as Jason isn't a part of Hex and not all Elixir versions support the new JSON module etc.
- how should we handle errors? Should we retry?
This task would be useful for agentic tools in addition to just human use, assuming that we format it as a human readable output. Right now it just dumps the raw JSON (which is fine for agents but bad for humans).
Open to thoughts/critiques, or happy to have this PR closed if this doesn't seem like something we want, or isn't in the place we want it.
I've fleshed this out very nicely in usage_rules, and I'm very happy to move some or all of that logic here ❤️
I wanted a good way to distribute and work on this in a way taht doesn't rely on users updating hex, and I wanted to be able to play w/ packages and formats etc.
https://github.com/user-attachments/assets/d946886a-631c-4e74-bd9d-a3d257ae458f
Should we present human readable output? If so, how do you want to go about handling JSON, as Jason isn't a part of Hex and not all Elixir versions support the new JSON module etc.
We can add support for "application/vnd.hex+erlang", to hexdocs, that uses erlang binary term format https://github.com/hexpm/hex/blob/main/lib/hex/api.ex#L6.
If we have elixir expose it's terminal markdown renderer (IO.ANSI.Docs) as public API we can even pretty print it.
how should we handle errors? Should we retry?
I think the caller should handle errors.
@zachdaniel we now have the new mix hex.search: #1094 My suggestion is to add something like mix hex.search --docs "foo" and by default it searches within the given project. It should print to the terminal. We can add --format json later.
