From 0e8dabc42346a230932f38d289812b8dd9c7aaa4 Mon Sep 17 00:00:00 2001 From: jacklinke Date: Sun, 26 May 2024 18:17:58 -0400 Subject: [PATCH] Continue improving documentation --- docs/conf.py | 13 ++++ docs/index.md | 2 +- docs/reference.md | 117 +++++++++++++++++++++------- docs/requirements.txt | 1 + noxfile.py | 4 +- src/django_segments/app_settings.py | 6 +- 6 files changed, 109 insertions(+), 34 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0d2eec4..12d9449 100644 --- a/docs/conf.py +++ b/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() diff --git a/docs/index.md b/docs/index.md index 9647fc9..f2f55e2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ end-before: ```{toctree} --- hidden: -maxdepth: 1 +maxdepth: 2 --- usage diff --git a/docs/reference.md b/docs/reference.md index 99a447c..57818a7 100644 --- a/docs/reference.md +++ b/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: ``` diff --git a/docs/requirements.txt b/docs/requirements.txt index fc882d6..b9f7df5 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/noxfile.py b/noxfile.py index 586219b..a2a0c0a 100644 --- a/noxfile.py +++ b/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(): diff --git a/src/django_segments/app_settings.py b/src/django_segments/app_settings.py index ccd1d72..bae4d7a 100644 --- a/src/django_segments/app_settings.py +++ b/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)