Add documentation

.github/workflows/continuous-deployment.yaml

@@ -4,6 +4,10 @@ on:
   push:
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint-python:
     name: Lint Python code

.github/workflows/docs.yaml

@@ -0,0 +1,78 @@
+name: Documentation
+
+on:
+  push:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v4
+
+      - id: setup-python
+        name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pipenv'
+
+      - id: install-pipenv
+        name: Install pipenv
+        run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
+        shell: bash
+
+      - id: install-python-dependencies
+        name: Install Python dependencies
+        run: pipenv sync --dev
+        shell: bash
+
+      - id: build-sphinx-documentation
+        name: Build Sphinx documentation
+        run: pipenv run make html
+        shell: bash
+        working-directory: docs
+
+      - id: upload-release-candidate
+        name: Upload release candidate
+        uses: actions/upload-artifact@v3
+        with:
+          name: release-candidate
+          path: ./docs/_build/html/
+
+  # deploy:
+  #   name: Deploy
+  #   runs-on: ubuntu-latest
+  #   needs: build
+  #   if: github.event_name == 'push' && github.branch == 'main'
+  #   steps:
+  #     - name: Download release candidate
+  #       uses: actions/download-artifact@v3
+  #       with:
+  #         name: release-candidate
+  #         path: ./docs/
+
+  #     - id: configure-aws
+  #       name: Configure AWS Credentials
+  #       uses: aws-actions/configure-aws-credentials@v1
+  #       with:
+  #         aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+  #         aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+  #         aws-region: ${{ secrets.AWS_REGION }}
+
+  #     - id: upload-to-s3
+  #       name: Upload documentation to Amazon S3
+  #       uses: datadesk/delivery-deploy-action@v1
+  #       with:
+  #         bucket: ${{ secrets.AWS_BUCKET }}
+  #         base-path: ${{ secrets.AWS_BASE_PATH }}
+  #         dir: ./docs/
+  #         should-cache: false
+  #         use-accelerate-endpoint: false
+  #         public: true

Pipfile

@@ -18,6 +18,13 @@ pep8-naming = "*"
 pytest = "*"
 pytest-env = "*"
 pytest-cov = "*"
+sphinx = "*"
+sphinx-autobuild = "*"
+sphinx-click = "*"
+sphinx-rtd-theme = "*"
+sphinxcontrib-napoleon = "*"
+sphinxcontrib-mermaid = "*"
+myst-parser = "*"
 
 [packages]
 exceptiongroup = "*"

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you have found a vulnerability in this project, please contact the project's maintainers via the email addresses on their GitHub profiles.

docs/Makefile

@@ -0,0 +1,23 @@
+# 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)
+
+livehtml:
+	sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html

docs/conf.py

@@ -0,0 +1,36 @@
+"""Configuration file for the Sphinx documentation builder."""
+import os
+import sys
+from datetime import datetime
+
+# Insert the parent directory into the path
+sys.path.insert(0, os.path.abspath("../your_source_code"))
+
+project = "your-package-name"
+year = datetime.now().year
+copyright = f"{year}"
+author = "your-name"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_baseurl = "/docs/"
+pygments_style = "sphinx"
+
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+extensions = [
+    "myst_parser",
+    "sphinx_click",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.mermaid",
+]

docs/index.md

@@ -0,0 +1,3 @@
+# Your package name
+
+Your documention starts here ...