21 files changed, 305 insertions, 0 deletions
diff --git a/docs.yml b/docs.yml
new file mode 100644
index 0000000..f7aa212
--- /dev/null
+++ b/docs.yml
@@ -0,0 +1,18 @@
+version: '3'
+
+services:
+  docs:
+    image: pyblackbird_cc_local_docs
+    container_name: pyblackbird_cc_local_docs
+    build:
+      context: .
+      dockerfile: ./compose/local/docs/Dockerfile
+    env_file:
+      - ./.envs/.local/.django
+    volumes:
+      - ./docs:/docs:z
+      - ./config:/app/config:z
+      - ./pyblackbird_cc:/app/pyblackbird_cc:z
+    ports:
+      - '9000:9000'
+    command: /start-docs
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..6957700
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,29 @@
+# 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
+APP = /app
+
+.PHONY: help livehtml apidocs Makefile
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
+
+# Build, watch and serve docs with live reload
+livehtml:
+	sphinx-autobuild -b html --host 0.0.0.0 --port 9000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html
+
+# Outputs rst files from django application code
+apidocs:
+	sphinx-apidoc -o $(SOURCEDIR)/api $(APP)
+
+# 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) -c .
diff --git a/docs/__init__.py b/docs/__init__.py
new file mode 100644
index 0000000..8772c82
--- /dev/null
+++ b/docs/__init__.py
@@ -0,0 +1 @@
+# Included so that Django's startproject comment runs against the docs directory
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..3dc1bc6
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,64 @@
+# ruff: noqa
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+import django
+
+if os.getenv("READTHEDOCS", default=False) == "True":
+    sys.path.insert(0, os.path.abspath(".."))
+    os.environ["DJANGO_READ_DOT_ENV_FILE"] = "True"
+    os.environ["USE_DOCKER"] = "no"
+else:
+    sys.path.insert(0, os.path.abspath("/app"))
+os.environ["DATABASE_URL"] = "sqlite:///readthedocs.db"
+os.environ["CELERY_BROKER_URL"] = os.getenv("REDIS_URL", "redis://redis:6379")
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.local")
+django.setup()
+
+# -- Project information -----------------------------------------------------
+
+project = "pyblackbird-cc"
+copyright = """2024, Matthew Lemon"""
+author = "Matthew Lemon"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
diff --git a/docs/howto.rst b/docs/howto.rst
new file mode 100644
index 0000000..73953de
--- /dev/null
+++ b/docs/howto.rst
@@ -0,0 +1,38 @@
+How To - Project Documentation
+======================================================================
+
+Get Started
+----------------------------------------------------------------------
+
+Documentation can be written as rst files in `pyblackbird_cc/docs`.
+
+
+To build and serve docs, use the commands::
+
+    docker compose -f local.yml up docs
+
+
+
+Changes to files in `docs/_source` will be picked up and reloaded automatically.
+
+`Sphinx <https://www.sphinx-doc.org/>`_ is the tool used to build documentation.
+
+Docstrings to Documentation
+----------------------------------------------------------------------
+
+The sphinx extension `apidoc <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_ is used to automatically document code using signatures and docstrings.
+
+Numpy or Google style docstrings will be picked up from project files and available for documentation. See the `Napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/>`_ extension for details.
+
+For an in-use example, see the `page source <_sources/users.rst.txt>`_ for :ref:`users`.
+
+To compile all docstrings automatically into documentation source files, use the command:
+    ::
+
+        make apidocs
+
+
+This can be done in the docker container:
+    ::
+
+        docker run --rm docs make apidocs
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..afb7889
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,24 @@
+.. pyblackbird-cc documentation master file, created by
+   sphinx-quickstart.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to pyblackbird-cc's documentation!
+======================================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   howto
+   pycharm/configuration
+   users
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..27675c2
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,46 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build -c .
+)
+set SOURCEDIR=_source
+set BUILDDIR=_build
+set APP=..\pyblackbird_cc
+
+if "%1" == "" goto help
+
+%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.Install sphinx-autobuild for live serving.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -b %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:livehtml
+sphinx-autobuild -b html --open-browser -p 9000 --watch %APP% -c . %SOURCEDIR% %BUILDDIR%/html
+GOTO :EOF
+
+:apidocs
+sphinx-apidoc -o %SOURCEDIR%/api %APP%
+GOTO :EOF
+
+:help
+%SPHINXBUILD% -b help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/pycharm/configuration.rst b/docs/pycharm/configuration.rst
new file mode 100644
index 0000000..fa53a8f
--- /dev/null
+++ b/docs/pycharm/configuration.rst
@@ -0,0 +1,70 @@
+Docker Remote Debugging
+=======================
+
+To connect to python remote interpreter inside docker, you have to make sure first, that Pycharm is aware of your docker.
+
+Go to *Settings > Build, Execution, Deployment > Docker*. If you are on linux, you can use docker directly using its socket  `unix:///var/run/docker.sock`, if you are on Windows or Mac, make sure that you have docker-machine installed, then you can simply *Import credentials from Docker Machine*.
+
+.. image:: images/1.png
+
+Configure Remote Python Interpreter
+-----------------------------------
+
+This repository comes with already prepared "Run/Debug Configurations" for docker.
+
+.. image:: images/2.png
+
+But as you can see, at the beginning there is something wrong with them. They have red X on django icon, and they cannot be used, without configuring remote python interpreter. To do that, you have to go to *Settings > Build, Execution, Deployment* first.
+
+
+Next, you have to add new remote python interpreter, based on already tested deployment settings. Go to *Settings > Project > Project Interpreter*. Click on the cog icon, and click *Add Remote*.
+
+.. image:: images/3.png
+
+Switch to *Docker Compose* and select `local.yml` file from directory of your project, next set *Service name* to `django`
+
+.. image:: images/4.png
+
+Having that, click *OK*. Close *Settings* panel, and wait few seconds...
+
+.. image:: images/7.png
+
+After few seconds, all *Run/Debug Configurations* should be ready to use.
+
+.. image:: images/8.png
+
+**Things you can do with provided configuration**:
+
+* run and debug python code
+
+.. image:: images/f1.png
+
+* run and debug tests
+
+.. image:: images/f2.png
+.. image:: images/f3.png
+
+* run and debug migrations or different django management commands
+
+.. image:: images/f4.png
+
+* and many others..
+
+Known issues
+------------
+
+* Pycharm hangs on "Connecting to Debugger"
+
+.. image:: images/issue1.png
+
+This might be fault of your firewall. Take a look on this ticket - https://youtrack.jetbrains.com/issue/PY-18913
+
+* Modified files in `.idea` directory
+
+Most of the files from `.idea/` were added to `.gitignore` with a few exceptions, which were made, to provide "ready to go" configuration. After adding remote interpreter some of these files are altered by PyCharm:
+
+.. image:: images/issue2.png
+
+In theory you can remove them from repository, but then, other people will lose a ability to initialize a project from provided configurations as you did. To get rid of this annoying state, you can run command::
+
+    $ git update-index --assume-unchanged pyblackbird_cc.iml
diff --git a/docs/pycharm/images/1.png b/docs/pycharm/images/1.png
new file mode 100644
index 0000000..06908a1
--- /dev/null
+++ b/docs/pycharm/images/1.png
diff --git a/docs/pycharm/images/2.png b/docs/pycharm/images/2.png
new file mode 100644
index 0000000..1fb8cf1
--- /dev/null
+++ b/docs/pycharm/images/2.png
diff --git a/docs/pycharm/images/3.png b/docs/pycharm/images/3.png
new file mode 100644
index 0000000..32c9335
--- /dev/null
+++ b/docs/pycharm/images/3.png
diff --git a/docs/pycharm/images/4.png b/docs/pycharm/images/4.png
new file mode 100644
index 0000000..cf07f9d
--- /dev/null
+++ b/docs/pycharm/images/4.png
diff --git a/docs/pycharm/images/7.png b/docs/pycharm/images/7.png
new file mode 100644
index 0000000..4f8807e
--- /dev/null
+++ b/docs/pycharm/images/7.png
diff --git a/docs/pycharm/images/8.png b/docs/pycharm/images/8.png
new file mode 100644
index 0000000..05946f2
--- /dev/null
+++ b/docs/pycharm/images/8.png
diff --git a/docs/pycharm/images/f1.png b/docs/pycharm/images/f1.png
new file mode 100644
index 0000000..2d8c4b6
--- /dev/null
+++ b/docs/pycharm/images/f1.png
diff --git a/docs/pycharm/images/f2.png b/docs/pycharm/images/f2.png
new file mode 100644
index 0000000..b123a47
--- /dev/null
+++ b/docs/pycharm/images/f2.png
diff --git a/docs/pycharm/images/f3.png b/docs/pycharm/images/f3.png
new file mode 100644
index 0000000..713ab54
--- /dev/null
+++ b/docs/pycharm/images/f3.png
diff --git a/docs/pycharm/images/f4.png b/docs/pycharm/images/f4.png
new file mode 100644
index 0000000..11668ec
--- /dev/null
+++ b/docs/pycharm/images/f4.png
diff --git a/docs/pycharm/images/issue1.png b/docs/pycharm/images/issue1.png
new file mode 100644
index 0000000..1bb68ee
--- /dev/null
+++ b/docs/pycharm/images/issue1.png
diff --git a/docs/pycharm/images/issue2.png b/docs/pycharm/images/issue2.png
new file mode 100644
index 0000000..174f6fd
--- /dev/null
+++ b/docs/pycharm/images/issue2.png
diff --git a/docs/users.rst b/docs/users.rst
new file mode 100644
index 0000000..1ddbc73
--- /dev/null
+++ b/docs/users.rst
@@ -0,0 +1,15 @@
+ .. _users:
+
+Users
+======================================================================
+
+Starting a new project, it’s highly recommended to set up a custom user model, 
+even if the default User model is sufficient for you. 
+
+This model behaves identically to the default user model, 
+but you’ll be able to customize it in the future if the need arises.
+
+.. automodule:: pyblackbird_cc.users.models
+   :members:
+   :noindex:
+