Closed ahuang11 closed 1 year ago
Here's prefect-gcp; it's flatly nested by module because when it's nested by class / methods, it becomes extremely noisy (like the API reference)
The examples in the blocks catalog seem a bit sparse and underwhelming since their all essentially the same. Would it make sense to also include examples for blocks in the blocks catalog? It would be duplicating the example in multiple places, but since we're generating those pages the maintenance cost would be low.
I think that's the intention of the Blocks Catalog to simply show what blocks are available and how to load the block. Maybe I should rename Examples Catalog to Examples Gallery?
Either way, I think we need more information about the blocks in the block gallery than just how to load them. Ideally it answers most high level questions a user could have when looking at blocks: what does it do, a simple complete example, and where to go to learn more.
Let me know if this is sufficient, or if you'd like to see anything else.
I think this is moving in the opposite direction that I was proposing. The approach I'm proposing is that each block would have the following:
I think the goal of a collection's block catalog is to get people interested in the blocks in a collection and/or quickly find the block that can address their use case. Let me know if that aligns with what you think the purpose of the collection block catalog is.
Yeah that sounds doable; I can parse the docstrings to do that, and perhaps add a second example to each of them.
Okay, added the description of the block.
Link to the API ref should be in the block's docstring.
To prevent duplication, I hyperlinked to the examples catalog.
This PR:
I think doing this will make users more willing to try since there's a dedicated examples section (at least when I see a new package, I would first look at their gallery of examples).
I envision, if we have specific highlights on how to use a collection effectively, we can also create a
usage_guide.md
similar to what we have for prefect-dask right now:This is what it looks like in prefect-openai Blocks Catalog:
Examples catalog: