add docs

Author: SimonBlanke

docs/README.md

@@ -0,0 +1,60 @@
+# Surfaces Documentation
+
+This directory contains the Sphinx documentation for the Surfaces library.
+
+## Building the Documentation
+
+### Prerequisites
+
+Install the documentation dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Building HTML Documentation
+
+From the `docs/source` directory:
+
+```bash
+make html
+```
+
+The built documentation will be in `docs/build/html/`.
+
+### Live Preview
+
+For development with auto-rebuild:
+
+```bash
+make livehtml
+```
+
+This starts a server at `http://127.0.0.1:8000` that auto-rebuilds on changes.
+
+### Cleaning Build Artifacts
+
+```bash
+make clean
+```
+
+## Structure
+
+```
+docs/
+├── build/              # Built documentation output
+├── requirements.txt    # Documentation dependencies
+├── README.md          # This file
+└── source/            # Documentation source files
+    ├── conf.py        # Sphinx configuration
+    ├── index.rst      # Main page
+    ├── _static/       # Static files (CSS, images)
+    ├── _templates/    # Custom templates
+    ├── api_reference/ # API documentation
+    ├── examples/      # Code examples
+    └── user_guide/    # User guide pages
+```
+
+## Theme
+
+The documentation uses the pydata-sphinx-theme with a custom dark pastel red color scheme. Custom CSS is in `source/_static/css/custom.css`.

docs/requirements.txt

@@ -0,0 +1,21 @@
+# Requirements for building Surfaces documentation
+
+# Core Sphinx and extensions
+sphinx>=7.0.0
+sphinx-autobuild
+sphinx-copybutton
+sphinx-design
+sphinx-issues
+myst-parser
+numpydoc
+
+# Theme
+pydata-sphinx-theme
+
+# For intersphinx linking
+# These need to be importable to build docs
+numpy
+pandas
+scikit-learn
+matplotlib
+plotly

docs/source/Makefile

@@ -0,0 +1,26 @@
+# 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)
+
+# Custom targets
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf $(BUILDDIR)/*