Include DryORM tool in the documentation

[tim-schilling]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

Include DryORM snippets in the Django documentation, specifically around confusing or complex topics.

Problem

There are several parts of the ORM that are a bit difficult to wrap your head around. Several of the notes on the queries topic page are complex ideas. Allowing readers to see the queries it generates and consider what the ORM is actually doing should improve understanding.

Request or proposal

proposal

Additional Details

DryORM is a tool from @omaraboumrad. It's been used by community members in Trac tickets and discussions to help others. The ORM is one of the best parts of Django and this tool does a fantastic job of showing what it's doing under the hood. Prominently displaying this in our documentation (maybe even the landing page!?!) could go a long way to helping people get comfortable with Django.

Implementation Suggestions

Currently @omaraboumrad manages this tool himself. The community has linked to other community maintained solutions such as Django Packages, Jazzband and Django Commons. However, this may be a little different as it's an interactive tool.

I think we'll be most productive if we hold off on the discussion around how to host the tool and first discuss whether this tool should be included in the documentation. I think it's reasonable to have concerns about an interactive tool being a part of the documentation and is fair game for initial discussion though.

[github-actions]

Thank you tim-schilling for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[carltongibson]

Yep, I think something like this would be super. AFAICS DryORM isn't open source right? (I know others have built similar, already 🤔)

[MrJico]

Yep, I think something like this would be super. AFAICS DryORM isn't open source right? (I know others have built similar, already 🤔)
it is now 🚀
https://github.com/omaraboumrad/dryorm

[tim-schilling]

One concern would be maintaining the code examples for the tool and the documentation. I think there's some trickiness involved there. Maybe we can supply the code to be used in DryORM so that the documentation can be the source of truth. I could see a future where this would allow us to short-hand code examples, then use DryORM to show the full code snippet (all the imports and model definitions).

[MrJico]

I think is would be a great edition to the already great django documentation, specify around ORM heavy parts like Models, Querysets, Managers.
one think i have noticed a lot is that quick testing and trying out new things if you don't have access to not that straight forward, specially for new comers, having a direct reference or an option to run them in DryORM or equivalent would be super.

[benbacardi]

I'm a big +1 on something like this.

It would be great if DryORM (or whatever equivalent gets vendored in here) worked in an embeddable/iframe-style setup so the examples in the documentation could be run (and edited/played with) entirely inline without leaving the docs.

Maybe we can supply the code to be used in DryORM so that the documentation can be the source of truth.

Perhaps there's a way so the documentation build step can create live snippets when published.

[nanorepublica]

One part of DryORM to call out is the learning journey that Omar built into it. This is essentially a bit of an ORM tutorial and could be linked from a few places or as Tim mentioned a prime piece of content for a landing page!

[knyghty]

oh I was gonna suggest this, and now I don't need to. Great!

[omaraboumrad]

Big +1 from me. Thank you for suggesting this!

Note: As not to derail the idea oriented discussion. I'll throw in a short YouMayNotNeedDryORM which would be fleshed out further in a technical oriented discussion.

We may need to consider a simpler implementation that relies less (if not at all) on the server, as the current objective is limited to the documentation. If we're willing to settle for sqlite as a backend, Compressed Base64URL as a shareable source, and a cache-able overhead of ~20mb download (pyodide + django), then the solution could end up living in the user's browser instead of a server.

DryORM brings in friendly urls, multiple backends, on-demand git ref loading, and other niceties that may be overkill for what the documentation portal ought to have.

MrJico: it is now 🚀

It has been since inception (2017)! ;-)

[omaraboumrad]

Here's a generated prototype that uses an embeddable, browser-only implementation, alongside an example based on Tim's original point. This could be a good foundation to brainstorm over. There are no servers involved, beyond hosting the static files.

Examples: You'll need to scroll a little bit to reach the Try It block.

Making Queries - Creating Objects
Making Queries - Querysets are lazy
Making Queries - Spanning multi-valued relationships (Tim's Original Sample)

You can click the icon to pop-out into a full playground (also browser-only)

How it works:

• The built docs are for Django 6.1
• The embed defaults to the same version used by the docs (which would realistically be the case)
• The documentation uses a couple of new directives: playground-embed and playground-file like so:

.. playground-embed::
   :title: Create and save the Blog object in your browser

   .. playground-file:: models.py

      # code here

   .. playground-file:: script.py

      # code here

• The document itself remains the source of truth, hence document changes across django versions must also change the embedded script.
• Embeds can also provide the settings.py to use. Omitting it will simply use a bare one.

Notes

• Pyodide & Django Versions are downloaded once and loaded from cache afterwards
• Django versions are picked up from https://pypi.org/pypi/Django/json with a couple of filters
• Pyodide is roughly ~3.5mb download and Django the usual ~8mb.
• Embeds hide the settings, full version (clicking the icon to pop out) shows the settings

This is just a proof of concept, no different than most similar solutions out-there, just integrated in the docs.

[tim-schilling]

@omaraboumrad I wonder if we may want to explore customizing the codeblock itself to have the tab/run option in the top padding, or a tab. Similar to how the code blocks for terminals occasionally support switching between Unix and Windows syntax.

The other thing I was thinking about was, would it be more efficient in any way if the dryorm element was singular and any of the options to use it would just emit the code into that element?