Add type annotations to the documentation and examples and general documentation suggestions

[LarsDu]

I'm going to admit, the HydraZen docs are borderline unreadable. Important background details such as that fact that Hydra has a singleton store and that HydraZen has an alternate way of adding to this store (which has changed in more recent version) are generally glossed over.

The opening example: "HydraZen at a glance" pushes regular python classes to store whereas virtually every other example uses builds to create a dataclass from such objects before putting them in the store.

The "create and launch a simple application" is especially frustrating as there are no type annotations making it clear what type player1 and player2 and are especially not useful as most people are interested in making configs for objects and not strings?

Perhaps far better than the docs would be updating this simple example:
https://github.com/mit-ll-responsible-ai/hydra-zen-examples/blob/main/image_classifier/hydra_zen_example/image_classifier/configs.py

Which seems wildly out of date?

[rsokl]

Important background details such as that fact that Hydra has a singleton store and that HydraZen has an alternate way of adding to this store (which has changed in more recent version) are generally glossed over.

The at-a-glance section cannot bog readers down with things like discussing a singleton config store. If you read the reference docs for hydra-zen's config store, I think it addresses your comments about providing context about Hydra's store as well as about the store's auto-config capabilities.

In general, users are expected to read the reference docs to gain a deep understanding of how hydra-zen works, whereas tutorials and how-to guides aim to show users how to accomplish specific tasks, whereas the reference & explanations go into more explanation for how things actually work. This breakdown of docs sections is in accordance with the diataxis framework for technical document authoring.

The "create and launch a simple application" is especially frustrating as there are no type annotations making it clear what type player1 and player2

Yeah I was torn about that. I didn't want people to think annotations were necessary, but I agree that they are a boon to readability, which is why the rest of the docs feature them.

and are especially not useful as most people are interested in making configs for objects and not strings

The first parts of the tutorial are meant to be as trivial as possible while exposing newcomers to hydra-zen; the next very sections in the tutorial have you configuring objects.

Perhaps far better than the docs would be updating this simple example

Yep that is out of date. I would like to update it when I find time; perhaps it should just be deleted. You might find this section to be a suitable supplement: https://mit-ll-responsible-ai.github.io/hydra-zen/how_to/using_scikit_learn.html

HydraZen docs are borderline unreadable

I'm genuinely sorry/bummed to hear that. hydra-zen is a challenging project to document because we build off of Hydra and cannot to afford to teach people about Hydra in full and then hydra-zen. I've worked hard on these docs and am eager to improve them; please feel free to open further issues or PRs if you have suggestions on sections that would be handy to see or other improvements. I would also be eager to effectively mirror some of Hydra's docs, but using hydra-zen's capabilities. Similar to this section.

[rsokl]

See #464

• Added annotations
• Added a link / call-out to store reference docs in at-a-glance
• Made the stale example repo private for now

[LarsDu]

Thanks for responding. Sorry if I was a little harsh earlier. I think there is a large amount of automagic that can be somewhat unclear from the examples. For example: the fact that task functions take the hydrated objects themselves and not config is not super clear, nor is it obvious that these hydrated objects are translated from the config store under the hood.

It might be good to summarize the sort of problems that HydraZen solves (some of which are covered well in the docs, others not-so-much):

I might try to open a doc PR in the near future to simplify things.

[LarsDu]

Just a followup, is there a revised replacement for the out-of-date example:
https://github.com/mit-ll-responsible-ai/hydra-zen-examples/blob/main/image_classifier/hydra_zen_example/image_classifier/configs.py

Even though it was out-of-date, I found it incredibly useful.

I'd be happy to provide a similar example for the community if that would be helpful?