diff --git a/docs/index.rst b/docs/index.rst index a8f656f..6b003b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ Wutta-Continuum This package adds data versioning/history for `WuttJamaican`_, using `SQLAlchemy-Continuum`_. -.. _WuttJamaican: https://rattailproject.org/docs/wuttjamaican/ +.. _WuttJamaican: https://docs.wuttaproject.org/wuttjamaican/ .. _SQLAlchemy-Continuum: https://sqlalchemy-continuum.readthedocs.io/en/latest/ @@ -20,7 +20,9 @@ This package adds data versioning/history for `WuttJamaican`_, using :maxdepth: 2 :caption: Documentation + narr/features narr/install + narr/usage .. toctree:: :maxdepth: 1 diff --git a/docs/narr/features.rst b/docs/narr/features.rst new file mode 100644 index 0000000..20b08a4 --- /dev/null +++ b/docs/narr/features.rst @@ -0,0 +1,26 @@ + +Features +======== + +The general idea is to provide an audit/versioning trail for important +data tables. + +Each table defined in the :term:`app model` can either be versioned, +or not. Nothing changes for a non-versioned table. + +For a "versioned" table, a secondary "versions" table is created, +schema for which is a superset of the original "versioned" table. +When records change in the original table, new "version" records are +added to the versions table. + +Therefore you can see how a record has changed over time, by +inspecting its corresponding versions. + +When any record changes (for any versioned table), a new "transaction" +record is also created. This identifies the user responsible, and +timestamp etc. Any new version records will tie back to this +transaction record. + +All this is made possible by SQLAlchemy-Continuum; the Wutta-Continuum +package mostly just adds config glue. See also +:doc:`sqlalchemy-continuum:index`. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 4959f96..1494d22 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -31,7 +31,7 @@ this package for database migrations. You should already have an [alembic] script_location = wuttjamaican.db:alembic - version_locations = wuttjamaican.db:alembic/versions wutta_continuum.db:alembic/versions + version_locations = wutta_continuum.db:alembic/versions poser.db:alembic/versions wuttjamaican.db:alembic/versions Then (as you would have done previously in :ref:`wuttjamaican:db-setup`) you can migrate your database to add the diff --git a/docs/narr/usage.rst b/docs/narr/usage.rst new file mode 100644 index 0000000..4d42288 --- /dev/null +++ b/docs/narr/usage.rst @@ -0,0 +1,41 @@ + +Usage +===== + +You can check the feature status with +:meth:`~wutta_continuum.app.WuttaContinuumAppProvider.continuum_is_enabled()`:: + + app = config.get_app() + + if not app.continuum_is_enabled(): + print("Oh no! Continuum is not enabled.") + +The rest of this will assume the feature is enabled. + + +Built-In Models +--------------- + +The following built-in models are versioned. So, when records are +added / modified / removed via the ORM, new version records are +automatically created for each of these: + +* :class:`~wuttjamaican:wuttjamaican.db.model.auth.Permission` +* :class:`~wuttjamaican:wuttjamaican.db.model.base.Person` +* :class:`~wuttjamaican:wuttjamaican.db.model.auth.Role` +* :class:`~wuttjamaican:wuttjamaican.db.model.auth.User` +* :class:`~wuttjamaican:wuttjamaican.db.model.auth.UserRole` + + +Object Versions +--------------- + +A versioned model works normally but also has a ``versions`` +attribute, which reflects the list of version records:: + + user = session.query(model.User).first() + + for version in user.versions: + print(version) + +See also :doc:`sqlalchemy-continuum:version_objects`.