Repository navigation
Add an 'Examples' page to the docs with fully functioning example applications #644
Description
There are a few cases of interesting usages that come up in issues, but which don't seem appropriate to put into our main docs (b/c we don't want to bloat our docs). If we had an Examples page in the docs, we could show off all of our cool ideas for how you can solve problems with webargs, but without disrupting the flow of the main documentation.
Specific cases which would be good candidates for example apps:
- Django App with CSRF-Removing Parser
- Axios Query-String Parser
- Setting a parser to use
unknown=RAISEon query params
I did a quick scan of closed issues until I hit the 5.x/6.0 transition point, then called it a day. Maybe there are other interesting examples in older issues? Or maybe we have things in other parts of the docs like the upgrade guide which would be nice to separate out (or even just duplicate).
Reacted by KimSia Sim
Activity
lafrech commentedon Oct 4, 2021
An alternative/complementary approach could be to add an examples section to the tests. This is a bit more advanced, since users must dig in the tests, but it ensures the code keeps working.
simkimsia commentedon Oct 6, 2021
I like to contribute by writing the examples that are more to do with Django. For e.g. after @sirosen help in this comment #640 (comment)
Separately (let me know if i should open a new issue or PR), i was wondering whether it would be better to directly skip over the csrf token in the existing djangoparser in the webargs codebase. From my pov of using Django quite extensively, it seems silly everytime i use webargs for a django project, i then need to write my own parser that overrides the pre_load method.
sirosen commentedon Oct 7, 2021
If you want to discuss further, please open a separate issue. For my part, I'm strongly against
webargshaving any special-case logic for specific fields unless it satisfies some much more stringent conditions. I'm happy to elaborate, but not in this issue.I like this idea a lot -- too often, examples go stale when projects cut major versions. It's even happened to us here! My ideal case is that we have
examples/full of examples, and then we use that in bothtests/examples/*.pyand in the docs. There'ssphinx-gallery, which looks appropriate, but maybe we can do this without even using an extension. I'll look into it sometime soon.lafrech commentedon Oct 7, 2021
Yeah, not sure how to put examples in the docs.
There are sphinx features (perhaps extensions) to display the whole source code of a page in the docs. Could this be enough?
Otherwise, maybe directing readers to the source code in the repo might be acceptable.
Ideally, what we want to display in the docs is only the relevant part of the example code, not the whole test, including boilerplate and test artifacts. But this can't really be automatized, can it?
Or we make sure that each test has a good dostring and the doc includes the docstring and the link to the source (GitHub or better a page in the docs displaying the source).
simkimsia commentedon Nov 22, 2021
is fine.
So what's the latest about examples in the docs? How do I contribute?