Add Sphinx documentation and publish to RTD.

.gitignore

@@ -30,3 +30,5 @@ logs*
 *.csv
 archived/
 dist*
+docs/_build/
+docs/source/autoapi/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  jobs:
+    post_install:
+      - pip install poetry
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      # VIRTUAL_ENV needs to be set manually for now.
+      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --only docs
+
+
+sphinx:
+  configuration: docs/source/conf.py

README.md

@@ -76,6 +76,8 @@ Clone and run:
 2. `poetry install`
 3. `poetry run python -m src.auto_archiver --config secrets/orchestration.yaml`
 
+Note: Add the plugin [poetry-shell-plugin](https://github.com/python-poetry/poetry-plugin-shell) and run `poetry shell` to activate the virtual environment.
+This allows you to run the auto-archiver without the `poetry run` prefix.
 
 </details><br/>
 
@@ -286,6 +288,46 @@ manual release to docker hub
   * `docker image tag auto-archiver bellingcat/auto-archiver:latest`
   * `docker push bellingcat/auto-archiver`
 
+
+### Building the Docs
+
+The documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/) and [AutoAPI](https://sphinx-autoapi.readthedocs.io/en/latest/) and hosted on ReadTheDocs.
+To build the documentation locally, run the following commands:
+
+**Install required dependencies:**
+- Install the docs group of dependencies: 
+```shell
+# only the docs dependencies
+poetry install --only docs
+
+# or for all dependencies 
+poetry install
+```
+- Either use [poetry-plugin-shell](https://github.com/python-poetry/poetry-plugin-shell) to activate the virtual environment: `poetry shell`
+- Or prepend the following commands with `poetry run`
+
+**Create the documentation:**
+- Build the documentation: 
+```
+# Using makefile (Linux/macOS):
+make -C docs html
+
+# or using sphinx directly (Windows/Linux/macOS):
+sphinx-build -b html docs/source docs/_build/html
+```
+- If you make significant changes and want a fresh build run: `make -C docs clean` to remove the old build files.
+
+**Viewing the documentation:**
+```shell
+# to open the documentation in your browser.
+open docs/_build/html/index.html
+
+# or run autobuild to automatically update the documentation when you make changes
+sphinx-autobuild docs/source docs/_build/html
+```
+
+
+
 #### RELEASE
 * update version in [version.py](src/auto_archiver/version.py)
 * go to github releases > new release > use `vx.y.z` for matching version notation

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/source/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+from importlib.metadata import metadata
+
+package_metadata = metadata("auto-archiver")
+project = package_metadata["name"]
+authors = package_metadata["authors"]
+release = package_metadata["version"]
+
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "autoapi.extension",            # Generate API documentation from docstrings
+    "myst_parser",                  # Markdown support
+    'sphinxcontrib.mermaid',        # Mermaid diagrams
+    "sphinx.ext.viewcode",          # Source code links
+    "sphinx.ext.napoleon",          # Google-style and NumPy-style docstrings
+    # "sphinx.ext.autodoc",           # Include custom docstrings
+    # 'sphinx.ext.autosummary',       # Summarize module/class/function docs
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+# -- AutoAPI Configuration ---------------------------------------------------
+autoapi_type = 'python'
+autoapi_dirs = ["../../src"]
+autodoc_typehints = "signature"     # Include type hints in the signature
+autoapi_ignore = []                 # Ignore specific modules
+autoapi_keep_files = True          # Option to retain intermediate JSON files for debugging
+autoapi_add_toctree_entry = True    # Include API docs in the TOC
+autoapi_template_dir = None         # Use default templates
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "imported-members",
+]
+
+
+# -- Markdown Support --------------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",          # ::: fences
+    "deflist",              # Definition lists
+    "html_admonition",      # HTML-style admonitions
+    "html_image",           # Inline HTML images
+    "replacements",         # Substitutions like (C)
+    "smartquotes",          # Smart quotes
+    "linkify",              # Auto-detect links
+    "substitution",         # Text substitutions
+]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'furo'
+# html_static_path = ['_static']
+