start refactoring

.github/workflows/ci-cd.yml

@@ -76,6 +76,31 @@ jobs:
       platforms: linux/amd64,linux/arm64
 
 
+  docs-build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.11'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install sphinx sphinx-book-theme
+    - name: Build Sphinx documentation
+      run: |
+        cd docs
+        make html
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html
+
+
   pypi-publish:
     name: PyPI Publish
     runs-on: ubuntu-latest

.gitignore

@@ -6,3 +6,4 @@
 dist/
 *.egg-info
 build/
+docs/_build/

Makefile

@@ -4,6 +4,13 @@ PYTHON = $(BIN)/python
 PIP = $(BIN)/pip
 TEST = pytest
 
+# Sphinx documentation
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SPHINXAPIDOC  ?= sphinx-apidoc
+SOURCEDIR     = docs
+BUILDDIR      = docs/_build
+
 # Self documenting commands
 .DEFAULT_GOAL := help
 .PHONY: help
@@ -61,12 +68,23 @@ lint: $(VENV)/bin/activate ## Run pre-commit hooks
 test: $(VENV)/bin/activate ## Run unit tests
 	$(PYTHON) -m $(TEST)
 
-build: $(VENV)/bin/activate ## Generate distrubition packages
+build-dist: $(VENV)/bin/activate ## Generate distrubition packages
 	$(PYTHON) -m build
 
+build-docs: ## Generate documentation
+	@printf "Building documentation\n"
+	@$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)" pg_upsert
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
 publish: $(VENV)/bin/activate ## Publish to PyPI
 	$(MAKE) lint
 	$(MAKE) test
-	$(MAKE) build
+	$(MAKE) build-dist
 	$(PYTHON) -m twine upload --repository pypi dist/*
 	$(MAKE) clean
+
+build: $(VENV)/bin/activate ## Build the project
+	$(MAKE) lint
+	$(MAKE) test
+	$(MAKE) build-dist
+	$(MAKE) build-docs

docs/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import pg_upsert
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pg_upsert"
+copyright = "2024, Caleb Grant"
+author = "Caleb Grant"
+
+# The short X.Y version.
+version = pg_upsert.__version__
+# The full version, including alpha/beta/rc tags.
+release = pg_upsert.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#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 = "sphinx_book_theme"
+
+html_static_path = ["_static"]
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False

docs/index.rst

@@ -0,0 +1,31 @@
+.. pg_upsert documentation master file, created by
+   sphinx-quickstart on Thu Jul 18 11:16:22 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+pg_upsert documentation
+=======================
+
+Release v\ |version|.
+
+**pg_upsert** is a Python package that runs not-NULL, Primary Key, Foreign Key, and Check Constraint checks on PostgreSQL staging tables then update and insert (upsert) data from staging tables to base tables.
+
+The API Documentation / Guide
+-----------------------------
+
+If you are looking for information on a specific function, class, or method,
+this part of the documentation is for you.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

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=source
+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/modules.rst

@@ -0,0 +1,7 @@
+pg_upsert
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   pg_upsert

docs/pg_upsert.rst

@@ -0,0 +1,21 @@
+pg\_upsert package
+==================
+
+Submodules
+----------
+
+pg\_upsert.pg\_upsert module
+----------------------------
+
+.. automodule:: pg_upsert.pg_upsert
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pg_upsert
+   :members:
+   :undoc-members:
+   :show-inheritance:

pg_upsert/__init__.py

@@ -1,3 +1,4 @@
-from .pg_upsert import upsert
+from ._version import __version__
+from .pg_upsert import PgUpsert, PostgresDB
 
-__all__ = ["upsert"]
+__all__ = ["PgUpsert", "PostgresDB"]

pg_upsert/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.4"