Add docs (#9)

* add

* add

* add

* add

Author: baseplate-admin

.readthedocs.yml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+    os: ubuntu-22.04
+    tools:
+        python: '3.12'
+        # You can also specify other tool versions:
+    jobs:
+        post_create_environment:
+            # Install poetry
+            # https://python-poetry.org/docs/#installing-manually
+            - pip install poetry
+            # Tell poetry to not use a virtual environment
+            - poetry config virtualenvs.create false
+        post_install:
+            # Install dependencies with 'docs' dependency group
+            # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+            - poetry install --with docs
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+    configuration: docs/conf.py
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+

django_ltree/managers.py

@@ -1,27 +1,30 @@
 from django.db import models
-
+from typing import TYPE_CHECKING
 from django_ltree.paths import PathGenerator
 
+from .querysets import TreeQuerySet
 
-class TreeQuerySet(models.QuerySet):
-    def roots(self):
-        return self.filter(path__depth=1)
-
-    def children(self, path):
-        return self.filter(path__descendants=path, path__depth=len(path) + 1)
+if TYPE_CHECKING:
+    from django_ltree.models import TreeModel
 
 
 class TreeManager(models.Manager):
     def get_queryset(self):
+        """Returns a queryset with the models ordered by `path`"""
         return TreeQuerySet(model=self.model, using=self._db).order_by("path")
 
-    def roots(self):
+    def roots(self) -> models.QuerySet["TreeModel"]:
+        """Returns the roots of a given model"""
         return self.filter().roots()
 
-    def children(self, path):
+    def children(self, path: str) -> models.QuerySet["TreeModel"]:
+        """Returns the childrens of a given object"""
         return self.filter().children(path)
 
-    def create_child(self, parent=None, **kwargs):
+    def create_child(
+        self, parent: "TreeModel" = None, **kwargs
+    ) -> models.QuerySet["TreeModel"]:
+        """Creates a tree child with or without parent"""
         paths_in_use = parent.children() if parent else self.roots()
         prefix = parent.path if parent else None
         path_generator = PathGenerator(

django_ltree/querysets.py

@@ -0,0 +1,14 @@
+from django.db import models
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import TreeModel
+
+
+class TreeQuerySet(models.QuerySet):
+    def roots(self) -> models.QuerySet["TreeModel"]:
+        return self.filter(path__depth=1)
+
+    def children(self, path: str) -> models.QuerySet["TreeModel"]:
+        return self.filter(path__descendants=path, path__depth=len(path) + 1)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "django_ltree"
+copyright = "2024, baseplate-admin"
+author = "baseplate-admin"
+release = "0.1.5"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+
+
+autodoc_typehints = "description"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,24 @@
+.. django_ltree documentation master file, created by
+   sphinx-quickstart on Sat Feb 24 21:13:02 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to django_ltree's documentation!
+========================================
+
+Augmenting `django` orm with postgres `ltree <https://www.postgresql.org/docs/current/ltree.html>`_ functionalities
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   manager
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,35 @@
+Installation
+============
+
+Requirements
+------------
+
+Python 3.10 to 3.12 supported.
+
+Django 4.2 to 5.0 supported.
+
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install django-ltree-2
+
+2. Add django-ltree to your ``INSTALLED_APPS``:
+
+   .. code-block:: python
+
+       INSTALLED_APPS = [
+           ...,
+           "django_ltree",
+           ...,
+       ]
+
+3. Run migrations:
+
+   .. code-block:: sh
+    
+        ./manage.py migrate

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/manager.rst

@@ -0,0 +1,17 @@
+Manager
+=======
+
+
+.. currentmodule:: django_ltree.managers
+    
+.. class:: TreeManager
+
+    This manager augments the django model, allowing it to be queried with tree specific queries
+
+    .. automethod:: get_queryset
+    
+    .. automethod:: roots
+    
+    .. automethod:: children
+
+    .. automethod:: create_child

docs/usage.rst

@@ -0,0 +1,78 @@
+Usage
+=====
+
+Lets assume that our model looks like this.
+
+.. code-block:: python 
+    
+    # models.py
+    from django import models
+    from django_ltree import TreeModel
+
+    class CustomTree(TreeModel):
+        text = models.TextField()
+
+
+Create a child without parent
+-----------------------------
+
+.. code-block:: python 
+
+    from .models import CustomTree
+
+    CustomTree.objects.create_child(text='Hello world')
+
+The following code with create a child with no parent (ie:roots of a tree)
+
+Create a child with parent
+--------------------------
+Let's assume we want to add a child to the CustomTree object of `pk 1`
+
+.. code-block:: python 
+
+    from .models import CustomTree
+
+    # This must return a single object
+    parent: CustomTree = CustomTree.objects.get(pk=1) 
+    CustomTree.objects.create_child(text='Hello world', parent=parent)
+
+
+Get all the roots of the model
+------------------------------
+A root means the the object that childrens anchor to.
+
+.. code-block:: python 
+
+    from .models import CustomTree
+
+    roots: list[CustomTree] = CustomTree.objects.roots()
+
+
+Get all the childrens of a object
+---------------------------------
+To get the childrens of a object, we can first get the object then call the QuerySet specific children function. 
+
+.. code-block:: python 
+
+    from .models import CustomTree
+
+    instance = CustomTree.objects.get(pk=1)
+
+    childrens: list[CustomTree] = instance.children()
+    
+
+
+Get the length of childrens of a object
+---------------------------------------
+`django` specific database functions still work when we call the filter method.
+
+Lets assume we want to get the childrens of `CustomTree` object whose pk is 1.
+
+.. code-block:: python 
+
+    from .models import CustomTree
+
+    instance = CustomTree.objects.get(pk=1)
+
+    childrens: int = instance.children().count()
+