docs: add basic feature, usage docs

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

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`.

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

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`.