Adds readthedocs documents and integration (#148)

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+# Build from the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt

.vscode/settings.json

@@ -4,4 +4,5 @@
     "python.envFile": "${workspaceFolder}/.envs",
     "python.linting.prospectorEnabled": true,
     "python.linting.enabled": true,
+    "esbonio.sphinx.confDir": "",
 }

README.md

@@ -1,4 +1,5 @@
-# django-multitenant [![Build Status](https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml/badge.svg)](https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml)
+# django-multitenant <br>[![Build Status](https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml/badge.svg)](https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml) [![Latest Documentation Status](https://readthedocs.org/projects/django-multitenant/badge/?version=latest)](https://django-multitenant.readthedocs.io/en/latest/?badge=latest)  [![Coverage Status](https://codecov.io/gh/citusdata/django-multitenant/branch/main/graph/badge.svg?token=taRgoSgHUw)](https://codecov.io/gh/citusdata/django-multitenant) [![PyPI Version](https://badge.fury.io/py/django-multitenant.svg)](https://badge.fury.io/py/django-multitenant)
+
 Python/Django support for distributed multi-tenant databases like Postgres+Citus
 
 Enables easy scale-out by adding the tenant context to your queries, enabling the database (e.g. Citus) to efficiently route queries to the right database node.

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     = source
+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/requirements.in

@@ -0,0 +1,4 @@
+sphinxnotes-strike
+sphinx
+sphinx_rtd_theme
+readthedocs-sphinx-search

docs/requirements.txt

@@ -0,0 +1,70 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile --output-file=requirements.txt --resolver=backtracking requirements.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.11.0
+    # via sphinx
+certifi==2022.12.7
+    # via requests
+charset-normalizer==3.0.1
+    # via requests
+docutils==0.18.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==6.0.0
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+markupsafe==2.1.2
+    # via jinja2
+packaging==23.0
+    # via sphinx
+pygments==2.14.0
+    # via sphinx
+pytz==2022.7.1
+    # via babel
+readthedocs-sphinx-search==0.2.0
+    # via -r requirements.in
+requests==2.28.2
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==6.1.3
+    # via
+    #   -r requirements.in
+    #   sphinx-rtd-theme
+    #   sphinxnotes-strike
+sphinx-rtd-theme==1.2.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jquery==2.0.0
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+sphinxnotes-strike==1.2
+    # via -r requirements.in
+urllib3==1.26.14
+    # via requests
+zipp==3.13.0
+    # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

docs/source/conf.py

@@ -0,0 +1,30 @@
+from datetime import date
+
+# 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 Multi-tenant"
+copyright = f"{date.today().year} .Citus Data Licensed under the MIT license, see License for details. "
+author = "Citus Data"
+release = "3.0.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinxnotes.strike"]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+language = "python"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/source/general.rst

@@ -0,0 +1,17 @@
+.. _general:
+
+Installation
+=================================
+
+1. ``pip install  --no-cache-dir django_multitenant``
+
+Supported Django and Citus versions/Pre-requisites
+===================================================
+
+================= ====== =====
+Python            Django Citus
+================= ====== =====
+3.7               3.2    10 11
+3.8 3.9 3.10 3.11 4.0    10 11
+3.8 3.9 3.10 3.11 4.1    11
+================= ====== =====

docs/source/index.rst

@@ -0,0 +1,53 @@
+.. Django Multi-tenant documentation master file, created by
+   sphinx-quickstart on Mon Feb 13 13:32:28 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Django Multi-tenant's documentation!
+=================================================
+
+|Latest Documentation Status| |Build Status| |Coverage Status| |PyPI Version|
+
+.. |Latest Documentation Status| image:: https://readthedocs.org/projects/django-multitenant/badge/?version=latest
+    :target: https://django-multitenant.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+.. |Build Status| image:: https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml/badge.svg
+   :target: https://github.com/citusdata/django-multitenant/actions/workflows/django-multitenant-tests.yml
+   :alt: Build Status
+
+.. |Coverage Status| image:: https://codecov.io/gh/citusdata/django-multitenant/branch/main/graph/badge.svg?token=taRgoSgHUw 
+   :target: https://codecov.io/gh/citusdata/django-multitenant
+   :alt: Coverage Status
+
+.. |PyPI Version| image:: https://badge.fury.io/py/django-multitenant.svg
+   :target: https://badge.fury.io/py/django-multitenant
+
+
+Python/Django support for distributed multi-tenant databases like
+Postgres+Citus
+
+Enables easy scale-out by adding the tenant context to your queries,
+enabling the database (e.g. Citus) to efficiently route queries to the
+right database node.
+
+There are architecures for building multi-tenant databases viz. **Create
+one database per tenant**, **Create one schema per tenant** and **Have
+all tenants share the same table(s)**. This library is based on the 3rd
+design i.e **Have all tenants share the same table(s)**, it assumes that
+all the tenant relates models/tables have a tenant_id column for
+representing a tenant.
+
+The following link talks more about the trade-offs on when and how to
+choose the right architecture for your multi-tenat database:
+
+https://www.citusdata.com/blog/2016/10/03/designing-your-saas-database-for-high-scalability/
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table Of Contents
+
+   general
+   usage
+   migration_mt_django
+   license

docs/source/license.rst

@@ -0,0 +1,20 @@
+License
+===============================================
+Copyright (c) 2023  , Citus Data Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.