WIP: mix hex.docs.search task

[zachdaniel]

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:

1. Should this be a thing at all?
2. 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.
3. 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.

[zachdaniel]

@josevalim per our conversation.

[zachdaniel]

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.

CleanShot_2025-07-17_at_15.12.21.mp4

[ericmj]

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.

[ericmj]

Would this task fit better under the existing mix hex.seach task? Less pollution of the task namespace.

[josevalim]

@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.