Add initial skeleton for Sphinx documentation

These changes have been triggered by running sphinx-build in the docs/
directory.

This PR also includes a new PHONY in the makefile for building the
documentation: `make docs`. This command will generate the HTML files
that produce a static site and place them in the build/docs folder.

A convenience and common make PHONY called "clean" has been added as
well, which will wipe out the build/ directory so that future commands
can run from scratch.

.pre-commit-config.yaml

@@ -37,3 +37,11 @@ repos:
         language: system
         types: [python]
         require_serial: true
+
+      - id: sphinx-lint
+        name: "lint the sphinx rst files in the docs folder"
+        entry: "sphinx-lint --sort-by filename"
+        language: python
+        types: [rst]
+        files: ^docs/
+        require_serial: true

docs/conf.py

@@ -0,0 +1,17 @@
+# 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 Postgres Migration Tools"
+copyright = "2024, Kraken Tech"
+author = "Kraken Tech"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx_rtd_theme"]
+html_theme = "sphinx_rtd_theme"

docs/index.rst

@@ -0,0 +1,9 @@
+Django Postgres Migration Tools Documentation
+=============================================
+
+Django Postgres Migration Tools provides extra functionalities to make Django
+migrations safer and more scalable.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

makefile

@@ -40,6 +40,13 @@ update:
 	uv pip compile pyproject.toml -q --upgrade --resolver=backtracking --extra=dev --output-file=requirements/development.txt
 	uv pip compile pyproject.toml -q --upgrade --resolver=backtracking --extra=pytest-in-nox --output-file=requirements/pytest-in-nox.txt
 
+.PHONY:docs
+docs:
+	sphinx-build docs/ build/docs -T -b html --fail-on-warning
+
+.PHONY:clean
+clean:
+	rm -rf build
 
 .PHONY:package
 package:

pyproject.toml

@@ -59,9 +59,15 @@ pytest-in-nox = [
     "pytest-django>=4.8.0",
     "pytest>=8.2.0",
 ]
+docs = [
+  "sphinx>=7.4.7",
+  "sphinx_rtd_theme>=2.0.0",
+  "sphinx_lint>=0.9.1",
+]
 dev = [
     # Testing
     "django_pg_migration_tools[pytest-in-nox]",
+    "django_pg_migration_tools[docs]",
     "django>=4.2.0",  # Django is needed for `make test`, but not for `nox`.
 
     # Linting

requirements/development.txt

@@ -1,15 +1,23 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile pyproject.toml --resolver=backtracking --extra=dev --output-file=requirements/development.txt
+alabaster==0.7.16
+    # via sphinx
 argcomplete==3.4.0
     # via nox
 asgiref==3.8.1
     # via
     #   django
     #   django-stubs
+babel==2.15.0
+    # via sphinx
 build==1.2.1
     # via django-pg-migration-tools (pyproject.toml)
+certifi==2024.7.4
+    # via requests
 cfgv==3.4.0
     # via pre-commit
+charset-normalizer==3.3.2
+    # via requests
 colorlog==6.8.2
     # via nox
 distlib==0.3.8
@@ -26,14 +34,26 @@ django-stubs==5.0.2
     # via django-pg-migration-tools (pyproject.toml)
 django-stubs-ext==5.0.2
     # via django-stubs
+docutils==0.20.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
 environs==11.0.0
     # via django-pg-migration-tools (pyproject.toml)
 filelock==3.15.4
     # via virtualenv
 identify==2.6.0
     # via pre-commit
+idna==3.7
+    # via requests
+imagesize==1.4.1
+    # via sphinx
 iniconfig==2.0.0
     # via pytest
+jinja2==3.1.4
+    # via sphinx
+markupsafe==2.1.5
+    # via jinja2
 marshmallow==3.21.3
     # via environs
 mypy==1.11.0
@@ -50,10 +70,13 @@ packaging==24.1
     #   marshmallow
     #   nox
     #   pytest
+    #   sphinx
 platformdirs==4.2.2
     # via virtualenv
 pluggy==1.5.0
     # via pytest
+polib==1.2.0
+    # via sphinx-lint
 pre-commit==3.7.1
     # via django-pg-migration-tools (pyproject.toml)
 psycopg==3.2.1
@@ -62,6 +85,8 @@ psycopg-binary==3.2.1
     # via psycopg
 psycopg2-binary==2.9.9
     # via django-pg-migration-tools (pyproject.toml)
+pygments==2.18.0
+    # via sphinx
 pyproject-hooks==1.1.0
     # via build
 pytest==8.3.1
@@ -74,8 +99,37 @@ python-dotenv==1.0.1
     # via environs
 pyyaml==6.0.1
     # via pre-commit
+regex==2024.5.15
+    # via sphinx-lint
+requests==2.32.3
+    # via sphinx
 ruff==0.5.4
     # via django-pg-migration-tools (pyproject.toml)
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.4.7
+    # via
+    #   django-pg-migration-tools (pyproject.toml)
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-jquery
+sphinx-lint==0.9.1
+    # via django-pg-migration-tools (pyproject.toml)
+sphinx-rtd-theme==2.0.0
+    # via django-pg-migration-tools (pyproject.toml)
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.6
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.8
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
 sqlparse==0.5.1
     # via django
 types-pyyaml==6.0.12.20240311
@@ -87,6 +141,8 @@ typing-extensions==4.12.2
     #   django-stubs-ext
     #   mypy
     #   psycopg
+urllib3==2.2.2
+    # via requests
 virtualenv==20.26.3
     # via
     #   nox