📝 Add docs page for self-referential model

[daniil-berg]

Purpose

Adds a new page explaining how to construct a self-referential/recursive relationship with SQLModel to the Advanced User Guide section of the documentation. This is arguably a fairly common use case that has been asked about and discussed in issue #127 already.

Code

The example code uses a Villain class/model for demonstration in an attempt at honoring the Hero theme of the documentation. A villain can have a boss villain and villain minions.

Additional info

The new page also includes a brief explanation of the sa_relationship_kwargs parameter of the Relationship constructor, since that is essential for defining the desired relationship. Depending on how @tiangolo wants to structure the rest of the advanced guide, this section may either need to be expanded or instead abbreviated to a short mention and link to a dedicated section for sa_-style parameters in SQLModel fields and relationships in the future.

Update (2022-08-02)

Rebased onto most recent version of the main branch (0.0.8 release, 75ce455).

Then rebased again, after adding tests to cover the new documentation example code. Coverage of the added code should now be at 100% (see latest codecov checks).

[jmehnle]

@tiangolo, what's blocking this from being merged?

[iloveitaly]

This is some really helpful documentation. @svlandeg anything we can do to get this merged?

[YuriiMotov]

@daniil-berg, thanks for working on this!

Great job!
I suggested a few minor improvements. Could you please take a look?

Also, we should probably create a group in Advanced (e.g. "Advanced Relationships") for other relationships-related sections such as #815

[github-actions]

📝 Docs preview

Last commit 53809d1 at: https://fef55e49.sqlmodel.pages.dev

Modified Pages

• https://fef55e49.sqlmodel.pages.dev/advanced/advanced-relationships/self-referential/ - (before)

[YuriiMotov]

LGTM!

[svlandeg]

I didn't review in detail (as Yurii already did 🙌), but just a few small nitpicks 😇

[RanaUniverse]

So currently what is the link of this self-reference docs link?
i wanted to make one for some days i was in trouble to found a way, as i dont know properly how to use sqlalchemy, so i wanted if there was any way in sqlmodel?

[RanaUniverse]

📝 Docs preview

Last commit 53809d1 at: https://fef55e49.sqlmodel.pages.dev

Modified Pages

• https://fef55e49.sqlmodel.pages.dev/advanced/advanced-relationships/self-referential/ - (before)

Today i read this docs, thinking the Villain example i made like this, i found and understand your explanations, i give you thanks for this easy explanation.

See i wanted to make a billing system where i need to keep record of product and its category, and i found category can have its own category like this, so after the Villain example you give in your article here i found i did something like this,

I am not properly sure is this a right way to use like this? or any problem it can happens here? Can you please check the `parent_id` & `parent_obj` field in the Sqlmodel class i made for category