feat: improve style for sphinx-sqlalchemy extension

docs/conf.py

@@ -28,6 +28,7 @@
     "numpydoc",
     "sphinx_sitemap",
     "sphinxcontrib.mermaid",
+    "sphinx_sqlalchemy",
 ]
 todo_include_todos = True
 autosummary_generate = True

docs/customisation/colors.rst

@@ -66,6 +66,10 @@ utilized by the Shibuya theme:
     --accent-a9: rgba(62, 127, 203, 0.81)
     --accent-a11: rgba(62, 127, 203, 0.92)
 
+.. tip::
+
+    You can generate colors with `radix custom paletteuse <https://www.radix-ui.com/colors/custom>`_.
+
 .. _global-dark-code:
 
 Dark code

docs/example_code/sqla_models.py

@@ -0,0 +1,30 @@
+"""Example SQLAlchemy ORM models."""
+
+from sqlalchemy import CheckConstraint, Column, ForeignKey, UniqueConstraint, orm, types
+
+Base = orm.declarative_base()
+
+
+class User(Base):
+    """A ``user``."""
+
+    __tablename__ = "dbusers"
+    __table_args__ = (UniqueConstraint("first_name", "last_name"),)
+    pk = Column(types.Integer, primary_key=True)
+    first_name = Column(types.String, doc="The name of the user.")
+    last_name = Column(types.String(255), doc="The surname of the user.")
+    dob = Column(types.Date, nullable=False, doc="The date of birth.")
+
+
+class Address(Base):
+    """An address."""
+
+    __tablename__ = "addresses"
+    __table_args__ = (CheckConstraint("number>0", name="check1"),)
+    pk = Column(types.Integer, primary_key=True)
+    number = Column(types.Integer, nullable=False, doc="The number of the address.")
+    postcode = Column(
+        types.String, nullable=False, index=True, doc="The postcode of the address."
+    )
+    user_id = Column(types.Integer, ForeignKey("dbusers.pk"))
+    user = orm.relationship("User")

docs/extensions/sphinx-sqlalchemy.rst

@@ -0,0 +1,38 @@
+sphinx-sqlalchemy
+=================
+
+Sphinx extension for documenting SQLAlchemy ORMs.
+
+- **Documentation**: https://sphinx-sqlalchemy.readthedocs.io/
+- **Source Code**: https://github.com/sphinx-extensions2/sphinx-sqlalchemy
+
+Usage
+-----
+
+Install ``sphinx_sqlalchemy``:
+
+.. code-block:: bash
+
+    pip install sphinx_sqlalchemy
+
+Add ``sphinx_sqlalchemy`` to your ``conf.py``:
+
+.. code-block:: python
+
+    extensions = [
+        'sphinx_sqlalchemy',
+    ]
+
+Example
+-------
+
+.. code-block:: none
+
+    .. sqla-model:: sqla_models.User
+
+    .. sqla-model:: ~sqla_models.Address
+
+
+.. sqla-model:: sqla_models.User
+
+.. sqla-model:: ~sqla_models.Address

docs/index.rst

@@ -76,6 +76,7 @@ Shibuya
     extensions/numpydoc
     extensions/mermaid
     extensions/docsearch
+    extensions/sphinx-sqlalchemy
 
 .. toctree::
     :caption: Development

requirements.txt

@@ -2,6 +2,7 @@ sphinx
 sphinx-sitemap
 sphinx-copybutton
 sphinx-design
+sphinx_sqlalchemy
 ipykernel
 jupyter-sphinx
 sphinx-togglebutton

static/css/contents/api-doc.css

@@ -1,12 +1,8 @@
-html.light {
-  --sig-property: var(--syntax-light-keyword);
-  --sig-name: var(--syntax-light-property);
-  --sig-typehint: var(--syntax-light-constant);
-}
-html.dark {
-  --sig-property: var(--syntax-dark-keyword);
-  --sig-name: var(--syntax-dark-property);
-  --sig-typehint: var(--syntax-dark-constant);
+:root {
+  --sig-property: var(--syntax-keyword);
+  --sig-name: var(--syntax-property);
+  --sig-typehint: var(--syntax-constant);
+  --sig-param: var(--syntax-meta);
 }
 
 dt.sig {

static/css/extensions/sphinx-sqlalchemy.css

@@ -0,0 +1,39 @@
+dl.sqla dt {
+  color: var(--sig-name);
+  margin-bottom: 0.5rem;
+}
+
+dl.sqla dt > em {
+  font-weight: 400;
+  font-style: normal;
+  color: var(--sig-param);
+}
+
+dl.sqla dd > p.rubric {
+  margin-top: 1.5rem;
+  text-transform: uppercase;
+  font-size: 0.76rem;
+}
+
+dl.sqla dd > p.rubric + .table-wrapper {
+  margin-top: 0.75rem;
+  border-left: 0;
+  border-right: 0;
+  border-radius: 0;
+}
+
+dl.sqla p.rubric + .table-wrapper th,
+dl.sqla p.rubric + .table-wrapper td {
+  border-left: 0;
+  border-right: 0;
+  background-color: transparent;
+}
+dl.sqla p.rubric + .table-wrapper td > p {
+  margin: 0;
+}
+dl.sqla p.rubric + .table-wrapper tr.row-odd {
+  background-color: transparent;
+}
+dl.sqla p.rubric + .table-wrapper tr.row-even {
+  background-color: var(--yue-c-row-background);
+}

static/css/modules.css

@@ -34,4 +34,5 @@
 @import "./extensions/nbsphinx.css";
 @import "./extensions/sphinx-gallery.css";
 @import "./extensions/docsearch.css";
+@import "./extensions/sphinx-sqlalchemy.css";
 @import "./extensions/misc.css";