cattrs
cattrs copied to clipboard
python-attrs
Recipes for initializer selection
Hi @Tinche,
here's a first draft for the "Recipes" page you suggested in #489. Let me know what you think and what needs to be adapted. Of course feel free to adjust examples and text as you like.
BTW: Should we add some tests for the recipes, or is there some automatic doc testing already in place (haven't yet looked too much into the repo mechanisms, tbh).
I like it!
Do you think we should export StructureHook (and UnstructureHook) from cattrs directly?
Should we add some tests for the recipes
You can use doctests. See an example here: https://github.com/python-attrs/cattrs/blob/3c4572fd28e587c02c1112904c981ff3a6c3801c/docs/customizing.md?plain=1#L68. You can run them using make doctests, and they get run on RTD when the docs get built. If they fail they stop the build, making someone take a look.
Also, I've been trying to use semantic newlines for docs, like attrs: https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#documentation. In practice, this means lines break not based on line length but a natural break (like a comma).
Hi @Tinche,
you mean making StructureHook and UnstructureHook available directly from the high-level cattrs namespace? I think that sound like a good idea. Would make it easier for people who prefer to annotate their hooks (like me 🙃).
I've tried my best to incorporate the requested changes. Was not 100% sure about the semantic newlines but tried to follow the style from the other .md files in the docs folder.
Let me know if you see other things that require changes (e.g. concerning the hook imports mentioned above). Otherwise, this PR is ready from my side 👌🏼
you mean making StructureHook and UnstructureHook available directly from the high-level cattrs namespace
Yeah, exactly.
In any case, great work. I might do an editing pass before releasing the next version.
Hi @Tinche, I saw the PR is now merged. Nice, thanks 🙏 Unfortunately, the code sections are not displayed properly, probably due to me messing with doctest and selecting the wrong label (sorry, have not worked with that plugin so far). Could you do me a favor and fix that part, since I'm currently traveling and have no PC with me for the next couple of weeks? Thanks and Cheers ✌️
Fixed it! Looks like doctest blocks don't do syntax highlighting unless they are written in the prompt style :/