Continue improving documentation

docs/conf.py

@@ -1,5 +1,11 @@
 """Sphinx configuration."""
 
+import os
+import sys
+
+import django
+
+
 project = "django-segments"
 author = "Jack Linke"
 copyright = "2024, Jack Linke"
@@ -11,3 +17,10 @@
 ]
 autodoc_typehints = "description"
 html_theme = "furo"
+
+# Add package path to sys.path
+sys.path.insert(0, os.path.join(os.path.abspath('.'), '../'))
+os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings'
+
+# Initialize Django
+django.setup()

docs/index.md

@@ -11,7 +11,7 @@ end-before: <!-- github-only -->
 ```{toctree}
 ---
 hidden:
-maxdepth: 1
+maxdepth: 2
 ---
 
 usage

docs/reference.md

@@ -1,64 +1,123 @@
 # Reference
 
-## django_segments
-
 ```{eval-rst}
-.. automodule:: django_segments
-   :members:
-```
-
-## admin.py
+admin.py
+========
 
-```{eval-rst}
 .. automodule:: django_segments.admin
     :members:
-```
 
-## apps.py
+apps.py
+=======
 
-```{eval-rst}
 .. automodule:: django_segments.apps
     :members:
-```
 
-## forms.py
+app_settings.py
+===============
+
+Package settings.
+
+.. data:: DJANGO_SEGMENTS_MODEL_BASE
+
+    Base model for all segment and span models. Default is :class:`django.db.models.base.ModelBase`. There should be no need to change this, but it is provided for advanced users.
+
+.. data:: POSTGRES_RANGE_FIELDS
+
+    Dictionary of field name and Python type that should be used to represent the range field. Default is:
+
+    .. code-block:: python
+
+        {
+            IntegerRangeField.__name__: int,
+            BigIntegerRangeField.__name__: int,
+            DecimalRangeField.__name__: float,
+            DateRangeField.__name__: datetime.date,
+            DateTimeRangeField.__name__: datetime,
+        }
+
+    This is used to convert the range field to a Python type when using the :meth:`django_segments.models.base.AbstractSpanMetaclass.get_range_field` method.
+
+.. data:: ON_DELETE_FOR_PREVIOUS
+
+    The behavior to use when deleting a segment or span that has a previous segment or span. Default is :attr:`django.db.models.CASCADE`.
+
+Global Span Configuration Options
+---------------------------------
+
+These options are used to configure the behavior of all Span models, and can be overridden on a per-model basis by adding a ``Config`` class with one or more of the corresponding setting names in lowercase to the span model. Example:
+
+.. code-block:: python
+
+    class MySpan(AbstractSpan):
+
+        class Config:
+            """Custom configuration options for this span."""
+
+            allow_gaps = False
+            soft_delete = False
+
+.. data:: ALLOW_GAPS
+
+        Allow gaps between segments in a span. Default is ``True``.
+
+.. data:: STICKY_BOUNDARIES
+
+        Force spans & segments to have sticky boundaries (if a range boundary for a span or segment is the same as another segment or the encompassing span, any changes to the boundary are proparated to the objects sharing that boundary). Default is ``True``.
+
+.. data:: SOFT_DELETE
+
+        Use soft delete for segments and spans. Default is ``True``.
+
+exceptions.py
+=============
+
+.. automodule:: django_segments.exceptions
+    :members:
+
+forms.py
+========
 
-```{eval-rst}
 .. automodule:: django_segments.forms
     :members:
-```
 
-## models/base.py
+models/base.py
+==============
 
-```{eval-rst}
 .. automodule:: django_segments.models.base
     :members:
-```
 
-## models/segment.py
+.. autoclass:: django_segments.models.base.AbstractSpanMetaclass
+   :members:
+   :no-index:
+   :special-members: __new__
+
+.. autoclass:: django_segments.models.base.AbstractSegmentMetaclass
+   :members:
+   :no-index:
+   :special-members: __new__
+
+models/segment.py
+=================
 
-```{eval-rst}
 .. automodule:: django_segments.models.segment
     :members:
-```
 
-## models/span.py
+models/span.py
+==============
 
-```{eval-rst}
 .. automodule:: django_segments.models.span
     :members:
-```
 
-## views.py
+views.py
+========
 
-```{eval-rst}
 .. automodule:: django_segments.views
     :members:
-```
 
-## urls.py
+urls.py
+=======
 
-```{eval-rst}
 .. automodule:: django_segments.urls
     :members:
 ```

docs/requirements.txt

@@ -2,3 +2,4 @@ furo==2024.5.6
 sphinx==7.3.7
 sphinx-click==6.0.0
 myst-parser==3.0.1
+psycopg2==2.9.9

noxfile.py

@@ -218,7 +218,7 @@ def docs_build(session: Session, django: str) -> None:
         args.insert(0, "--color")
 
     session.install(".")
-    session.install("sphinx", "sphinx-click", "furo", "myst-parser")
+    session.install("sphinx", "sphinx-click", "furo", "myst-parser", "psycopg2")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():
@@ -233,7 +233,7 @@ def docs(session: Session, django: str) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     args = session.posargs or ["--open-browser", "docs", "docs/_build"]
     session.install(".")
-    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser")
+    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser", "psycopg2")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():

src/django_segments/app_settings.py

@@ -17,7 +17,8 @@
 # There is likely no reason ever to change the model base, but it is provided as an setting here for completeness.
 DJANGO_SEGMENTS_MODEL_BASE = getattr(settings, "DJANGO_SEGMENTS_MODEL_BASE", ModelBase)
 
-# Define the allowed PostgreSQL range field types
+# Define the allowed PostgreSQL range field types as a dictionary where the key is the field name and the value is the
+# Python type that should be used to represent the range field.
 POSTGRES_RANGE_FIELDS = getattr(
     settings,
     "POSTGRES_RANGE_FIELDS",
@@ -40,7 +41,8 @@
 # - models.DO_NOTHING
 ON_DELETE_FOR_PREVIOUS = getattr(settings, "ON_DELETE_FOR_PREVIOUS", models.CASCADE)
 
-# Global configuration settings for Span models
+# Global configuration settings for Span models. These settings can be overridden by setting the same attributes on the
+# concrete Span model.
 ALLOW_GAPS = getattr(settings, "ALLOW_GAPS", True)
 STICKY_BOUNDARIES = getattr(settings, "STICKY_BOUNDARIES", True)
 SOFT_DELETE = getattr(settings, "SOFT_DELETE", True)