Docs improvements

CHANGELOG.rst

@@ -80,8 +80,8 @@ Other changes:
 
 Features:
 
-*  ``sqlalchemy.Enum`` fields generate a corresponding ``marshmallow.fields.Enum`` field
-  (:issue:`485`, :issue:`112`). Thanks :user:`panda-byte` for the PR.
+* ``sqlalchemy.Enum`` fields generate a corresponding ``marshmallow.fields.Enum`` field (:issue:`485`, :issue:`112`). 
+  Thanks :user:`panda-byte` for the PR.
 
 Support:
 
@@ -149,7 +149,7 @@ Other changes:
 Bug fixes:
 
 * Address ``DeprecationWarning`` re: usage of ``distutils`` (:pr:`435`).
- Thanks :user:`Tenzer` for the PR.
+  Thanks :user:`Tenzer` for the PR.
 
 0.28.0 (2022-03-09)
 +++++++++++++++++++
@@ -182,7 +182,7 @@ Other changes:
 Bug fixes:
 
 * Fix generating fields for ``postgreql.ARRAY`` columns (:issue:`392`).
- Thanks :user:`mjpieters` for the catch and patch.
+  Thanks :user:`mjpieters` for the catch and patch.
 
 0.26.0 (2021-05-26)
 +++++++++++++++++++

CONTRIBUTING.rst

@@ -89,13 +89,13 @@ Documentation
 
 Contributions to the documentation are welcome. Documentation is written in `reStructuredText`_ (rST). A quick rST reference can be found `here <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_. Builds are powered by Sphinx_.
 
-To build the docs in "watch" mode:
+To build and serve the docs in "watch" mode:
 
 .. code-block:: shell-session
 
-   $ tox -e watch-docs
+   $ tox -e docs-serve
 
-Changes in the `docs/` directory will automatically trigger a rebuild.
+Changes to documentation will automatically trigger a rebuild.
 
 
 .. _Sphinx: https://www.sphinx-doc.org/

README.rst

@@ -8,7 +8,6 @@ Homepage: https://marshmallow-sqlalchemy.readthedocs.io/
 
 `SQLAlchemy <http://www.sqlalchemy.org/>`_ integration with the  `marshmallow <https://marshmallow.readthedocs.io/en/latest/>`_ (de)serialization library.
 
-.. start elevator-pitch
 
 Declare your models
 ===================
@@ -52,6 +51,8 @@ Declare your models
 
     Base.metadata.create_all(engine)
 
+.. start elevator-pitch
+
 Generate marshmallow schemas
 ============================
 

docs/_static/custom.css

@@ -10,12 +10,6 @@ h2, h3, h4, h5, h6 {
   font-family: -apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif;
 }
 
-/* Links */
-
-a:link, a:visited {
-  color: var(--color-link);
-}
-
 /* Hide ToC caption text within the main body (but leave them in the side-bar). */
 /* https://github.com/hynek/structlog/blob/b488a8bf589a01aabc41e3bf8df81a9848cd426c/docs/_static/custom.css#L17-L20 */
 #furo-main-content span.caption-text {

docs/conf.py

@@ -6,6 +6,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinx_issues",
     "sphinxext.opengraph",
 ]
@@ -46,6 +47,7 @@
     },
     "top_of_page_buttons": ["view"],
 }
+pygments_dark_style = "lightbulb"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 html_show_sourcelink = False

docs/index.rst

@@ -12,6 +12,92 @@ Release v\ |version| (:ref:`Changelog <changelog>`)
 
 ----
 
+Declare your models
+===================
+
+.. tab-set::
+
+    .. tab-item:: SQLAlchemy 1.4
+        :sync: sqla1
+
+        .. code-block:: python
+
+            import sqlalchemy as sa
+            from sqlalchemy.orm import (
+                DeclarativeBase,
+                backref,
+                relationship,
+                sessionmaker,
+            )
+
+            from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field
+
+            engine = sa.create_engine("sqlite:///:memory:")
+            Session = sessionmaker(engine)
+
+
+            class Base(DeclarativeBase):
+                pass
+
+
+            class Author(Base):
+                __tablename__ = "authors"
+                id = sa.Column(sa.Integer, primary_key=True)
+                name = sa.Column(sa.String, nullable=False)
+
+                def __repr__(self):
+                    return f"<Author(name={self.name!r})>"
+
+
+            class Book(Base):
+                __tablename__ = "books"
+                id = sa.Column(sa.Integer, primary_key=True)
+                title = sa.Column(sa.String)
+                author_id = sa.Column(sa.Integer, sa.ForeignKey("authors.id"))
+                author = relationship("Author", backref=backref("books"))
+
+    .. tab-item:: SQLAlchemy 2
+        :sync: sqla2
+
+        .. code-block:: python
+
+            import sqlalchemy as sa
+            from sqlalchemy.orm import (
+                DeclarativeBase,
+                backref,
+                relationship,
+                sessionmaker,
+                mapped_column,
+                Mapped,
+            )
+
+            from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field
+
+            engine = sa.create_engine("sqlite:///:memory:")
+            Session = sessionmaker(engine)
+
+
+            class Base(DeclarativeBase):
+                pass
+
+
+            class Author(Base):
+                __tablename__ = "authors"
+                id: Mapped[int] = mapped_column(primary_key=True)
+                name: Mapped[str] = mapped_column(nullable=False)
+
+                def __repr__(self):
+                    return f"<Author(name={self.name!r})>"
+
+
+            class Book(Base):
+                __tablename__ = "books"
+                id: Mapped[int] = mapped_column(primary_key=True)
+                title: Mapped[str] = mapped_column()
+                author_id: Mapped[int] = mapped_column(sa.ForeignKey("authors.id"))
+                author: Mapped["Author"] = relationship("Author", backref=backref("books"))
+
+
 .. include:: ../README.rst
     :start-after: .. start elevator-pitch
     :end-before: .. end elevator-pitch

pyproject.toml

@@ -32,6 +32,7 @@ Source = "https://github.com/marshmallow-code/marshmallow-sqlalchemy"
 docs = [
   "furo==2024.8.6",
   "sphinx-copybutton==0.5.2",
+  "sphinx-design==0.6.1",
   "sphinx-issues==5.0.0",
   "sphinx==8.1.3",
   "sphinxext-opengraph==0.9.1",

tox.ini

@@ -34,12 +34,12 @@ commands = sphinx-build docs/ docs/_build {posargs}
 
 ; Below tasks are for development only (not run in CI)
 
-[testenv:watch-docs]
+[testenv:docs-serve]
 deps = sphinx-autobuild
 extras = docs
-commands = sphinx-autobuild --open-browser docs/ docs/_build {posargs} --watch src/marshmallow_sqlalchemy --delay 2
+commands = sphinx-autobuild --port=0 --open-browser --delay=2 docs/ docs/_build {posargs} --watch src --watch CONTRIBUTING.rst --watch README.rst
 
-[testenv:watch-readme]
+[testenv:readme-serve]
 deps = restview
 skip_install = true
 commands = restview README.rst