Simonletort da/1034 from the docs site, users do not know how they can suggest changes to the docs

.devcontainer.json

@@ -0,0 +1,3 @@
+{
+  "image": "ghcr.io/zombiezen/codespaces-nix"
+}

.gitignore

@@ -71,3 +71,4 @@ apps/splitwell/src/test/resources/splitwell-bundle*.tar.gz
 **/SingletonCookie
 __pycache__/
 docs/src/deployment/observability/metrics_reference.rst
+docs/build/

CONTRIBUTING.md

@@ -173,3 +173,5 @@ We publish docs from each commit from `main` to
 https://hyperledger-labs.github.io/splice/. This can
 often be useful to answer support requests with a docs link even if
 those docs are still very recent.
+
+Refer to [docs/README.md](docs/README.md) for details on how to contribute to the documentation.

docs/.gitignore

@@ -1,2 +1,4 @@
 src/app_dev/api
-html/
+html/
+venv/
+build/

docs/Makefile

@@ -0,0 +1,37 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXAUTOBUILD = sphinx-autobuild
+SOURCEDIR     = src
+BUILDDIR      = build
+
+# Put all phony targets here so that file names with the same name as phony targets
+# will not confuse make.
+.PHONY: help html livehtml clean
+
+# Default target: show help.
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to build the HTML documentation"
+	@echo "  livehtml   to automatically rebuild and preview the site on changes"
+	@echo "  clean      to remove all build files"
+
+# Build the HTML documentation
+html:
+	@echo "Building HTML documentation..."
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)
+	@echo "Build finished. Open $(BUILDDIR)/html/index.html to view."
+
+# Run the live-reloading server for previewing
+livehtml:
+	@echo "Starting live-reloading server..."
+	@echo "Your browser should open automatically. Press Ctrl+C to stop."
+	$(SPHINXAUTOBUILD) $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)
+
+# Remove all generated build files
+clean:
+	@echo "Cleaning build directory..."
+	rm -rf $(BUILDDIR)/*

docs/README.md

@@ -1,6 +1,10 @@
 # Docs
 
-Documentation for all CC functionality.
+Developer Documentation for all Splice functionalities.
+
+## Contributing to the Splice docs
+
+In order to setup your development environment, please see the [Development README](../DEVELOPMENT.md).
 
 ## Development Builds
 
@@ -19,3 +23,19 @@ or other changes that are not picked up by `sphinx-autobuild`.
 ### Changes
 
 When making a change, rebuild the documentation using `sbt docs/bundle`.
+
+## Simplified build
+
+For non developers who would rather not [setup a full developer environmnet](../DEVELOPMENT.md), you can preview a version of the doc by:
+
+- Installing the requirements for the doc only: 
+
+```bash
+./install-docs-requirements.sh
+```
+
+- Building the docs locally:
+
+```bash
+make livehtml
+```

docs/build-sphinx-docs.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -eou pipefail
+
+root_dir=$(cd "$(dirname $0)"; cd ..; pwd -P)
+input_dir="${root_dir}/docs/src"
+preview_dir="${root_dir}/docs/preview"
+config_dir="${root_dir}/docs/src"
+
+# Let's remove the dir to be 100% sure there are no stale files
+# The build is relatively small and we can afford it
+rm -Rf $preview_dir
+
+sphinx-build -M html $input_dir $preview_dir --fresh-env --conf-dir $config_dir --fail-on-warning
+
+# Make the generated files read-only
+find $preview_dir -type f -follow -exec chmod 0444 {} +
+
+if [[ $# -gt 0 && "$1" == "--with-preview" ]]; then
+  python -m http.server -d ./doc/preview/html
+fi
+
+
+#####
+# install
+#####
+# brew install pyenv
+# pyenv install 3.10.13
+# cd /Users/simonletort/Documents/GitHub/splice
+# pyenv local 3.10.13
+# pyenv virtualenv 3.10.13 splice-docs
+# pyenv local splice-docs
+# pip install sphinx sphinx-autobuild pyyaml
+# which python
+# python --version

docs/conf.py

@@ -0,0 +1,27 @@
+# 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 = 'Sphinx'
+copyright = '2025, Ethan Cohen'
+author = 'Ethan Cohen'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,17 @@
+.. Sphinx documentation master file, created by
+   sphinx-quickstart on Tue Jun 17 14:38:50 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Sphinx documentation
+====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+

docs/install-docs-requirements.sh

@@ -0,0 +1,75 @@
+#!/bin/zsh
+
+# Script to install requirements for building Sphinx docs locally
+
+set -e
+# Check for Xcode Command Line Tools
+if ! xcode-select -p &>/dev/null; then
+    echo "Xcode Command Line Tools not found. Installing..."
+    xcode-select --install
+    echo "Check for the install xcode dialog box. Please complete the Xcode Command Line Tools installation, then re-run this script."
+    exit 1
+fi
+
+# Check for Homebrew and install if missing
+if ! command -v brew &>/dev/null; then
+    echo "Homebrew not found. Installing Homebrew..."
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    # Add Homebrew to PATH for current session
+    if [[ -d "/opt/homebrew/bin" ]]; then
+        export PATH="/opt/homebrew/bin:$PATH"
+    elif [[ -d "/usr/local/bin" ]]; then
+        export PATH="/usr/local/bin:$PATH"
+    fi
+fi
+
+# Check for pyenv and install if missing
+if ! command -v pyenv &>/dev/null; then
+    echo "pyenv not found. Installing with Homebrew..."
+    if ! command -v brew &>/dev/null; then
+        echo "Homebrew is required to install pyenv. Please install Homebrew first."
+        exit 1
+    fi
+    brew install pyenv
+fi
+
+# Ensure desired Python version is installed via pyenv
+PYTHON_VERSION="3.11.9"
+if ! pyenv versions --bare | grep -qx "$PYTHON_VERSION"; then
+    echo "Installing Python $PYTHON_VERSION with pyenv..."
+    pyenv install "$PYTHON_VERSION"
+fi
+
+# Create virtual environment using pyenv if not exists
+if [ ! -d "venv" ]; then
+    pyenv shell "$PYTHON_VERSION"
+    python -m venv venv-splice-docs
+    echo "Created virtual environment in ./venv using pyenv Python $PYTHON_VERSION"
+fi
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Upgrade pip
+pip install --upgrade pip
+
+# Install additional requirements if requirements.txt exists
+echo "Installing build requirements..."
+if [ -f "requirements.txt" ]; then
+    pip install -r requirements.txt
+fi
+
+# Check for direnv and install if missing
+if ! command -v direnv &>/dev/null; then
+    echo "direnv not found. Installing with Homebrew..."
+    if ! command -v brew &>/dev/null; then
+        echo "Homebrew is required to install direnv. Please install Homebrew first."
+        exit 1
+    fi
+    brew install direnv
+fi
+
+export SPLICE_ROOT="${PWD}"
+
+echo "Sphinx documentation build requirements installed."
+# echo "To activate the virtual environment, run: source venv/bin/activate"

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

@@ -0,0 +1,7 @@
+pyyaml
+sphinx
+sphinx_rtd_theme
+sphinx-copybutton
+sphinx_reredirects
+sphinxcontrib-openapi
+sphinx-autobuild