Merge pull request #11 from quant-sci/add-docs

feat: add docs with sphinx

Author: Kleyt0n

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,15 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route unknown targets to sphinx-build.
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/.gitkeep

@@ -0,0 +1,52 @@
+Algorithms
+==========
+
+Classical computational-geometry algorithms.
+
+Convex hull
+-----------
+
+.. automodule:: cgeom.algorithms._convexhull
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Delaunay triangulation
+----------------------
+
+.. automodule:: cgeom.algorithms._delaunay
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Voronoi diagram
+---------------
+
+.. automodule:: cgeom.algorithms._voronoi
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Minimum enclosing circle
+------------------------
+
+.. automodule:: cgeom.algorithms._mincircle
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Segment intersection
+--------------------
+
+.. automodule:: cgeom.algorithms._intersection
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Polygon triangulation
+---------------------
+
+.. automodule:: cgeom.algorithms._triangulation
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/algorithms.rst

@@ -0,0 +1,20 @@
+Elements
+========
+
+Geometric primitives and the Pydantic input-validation models.
+
+Primitives
+----------
+
+.. automodule:: cgeom.elements.elements
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Input models
+------------
+
+.. automodule:: cgeom.elements.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/elements.rst

@@ -0,0 +1,12 @@
+# API reference
+
+Auto-generated reference documentation for the `cgeom` package, built from the
+in-source docstrings.
+
+```{toctree}
+:maxdepth: 2
+
+elements
+algorithms
+visualization
+```

docs/api/index.md

@@ -0,0 +1,9 @@
+Visualization
+=============
+
+Matplotlib-based plotting helpers, one per algorithm.
+
+.. automodule:: cgeom.visualization._plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/visualization.rst

@@ -0,0 +1,101 @@
+"""Sphinx configuration for the compute-geometry documentation."""
+
+import os
+import sys
+from datetime import date
+
+# Make the cgeom package importable for autodoc.
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -----------------------------------------------------
+
+project = "compute-geometry"
+author = "Kleyton da Costa"
+copyright = f"{date.today().year}, {author}"
+
+# Pull the version straight from the installed package metadata.
+try:
+    from importlib.metadata import version as _version
+
+    release = _version("compute-geometry")
+except Exception:  # pragma: no cover - fallback when not installed
+    release = "0.1.2"
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# -- Autodoc / autosummary ---------------------------------------------------
+
+autosummary_generate = True
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+# Napoleon understands the Google-style docstrings used across the codebase.
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_use_rtype = False
+
+# -- Intersphinx -------------------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+}
+
+# -- MyST --------------------------------------------------------------------
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "smartquotes",
+]
+myst_heading_anchors = 3
+
+# -- HTML output (Furo theme) ------------------------------------------------
+
+html_theme = "furo"
+html_title = "compute-geometry"
+html_static_path = ["_static"]
+html_logo = "../public/logo.svg"
+html_favicon = "../public/logo.svg"
+
+html_theme_options = {
+    "sidebar_hide_name": True,
+    "navigation_with_keys": True,
+    "source_repository": "https://github.com/kleyt0n/compute-geometry",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "light_css_variables": {
+        "color-brand-primary": "#0466c8",
+        "color-brand-content": "#0466c8",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#5b8def",
+        "color-brand-content": "#5b8def",
+    },
+}

docs/conf.py

@@ -0,0 +1,103 @@
+# Algorithms
+
+The `cgeom.algorithms` module bundles classical computational-geometry
+algorithms. Each is a class constructed from a set of points (or segments) and
+validated through the matching Pydantic input model.
+
+```python
+from cgeom.algorithms import (
+    ConvexHull,
+    DelaunayTriangulation,
+    VoronoiDiagram,
+    MinimumCircle,
+    SegmentIntersection,
+    PolygonTriangulation,
+)
+```
+
+## ConvexHull
+
+Computes the convex hull of a point set with the Gift Wrapping (Jarvis march)
+algorithm.
+
+```python
+points = [(326, 237), (373, 209), (378, 265), (443, 241),
+          (396, 231), (416, 270), (361, 335), (324, 297)]
+
+hull = ConvexHull(points)
+hull.convex_hull()        # ordered hull vertices [[x, y], ...]
+hull.get_indexes()        # indices of the input points on the hull
+```
+
+Construction requires at least 3 non-collinear points.
+
+## DelaunayTriangulation
+
+Builds the Delaunay triangulation of a point set.
+
+```python
+dt = DelaunayTriangulation(points)
+dt.triangulate()          # list of index triples
+dt.get_edges()            # unique edges
+dt.get_circumcircles()    # circumcircle of each triangle
+```
+
+## VoronoiDiagram
+
+Builds the Voronoi diagram — the dual of the Delaunay triangulation.
+
+```python
+import numpy as np
+
+points = np.loadtxt("examples/points1.txt")
+voronoi = VoronoiDiagram(points)
+cells = voronoi.build_voronoi_diagram()
+```
+
+## MinimumCircle
+
+Finds the smallest enclosing circle of a point set.
+
+```python
+mc = MinimumCircle()
+mc.minimum_circle([(0, 0), (1, 0), (0, 1), (1, 1)])   # [[cx, cy], radius]
+```
+
+## SegmentIntersection
+
+Reports all pairwise intersections of a set of segments. The primary method uses
+the Bentley–Ottmann sweep-line algorithm; a brute-force method is provided for
+verification.
+
+```python
+segments = [
+    [[0, 0], [4, 4]],
+    [[0, 4], [4, 0]],
+    [[0, 2], [4, 2]],
+    [[2, 0], [2, 4]],
+]
+
+si = SegmentIntersection(segments)
+si.find_intersections()              # sweep line
+si.find_intersections_brute_force()  # verification
+si.get_intersection_pairs()          # (i, j, point) tuples
+```
+
+## PolygonTriangulation
+
+Triangulates a simple polygon.
+
+```python
+pt = PolygonTriangulation([[0, 0], [4, 0], [4, 4], [0, 4]])
+pt.triangulate()
+```
+
+## Input validation
+
+Every algorithm validates its input through a Pydantic model in
+`cgeom.elements.models` (for example, `ConvexHullInput`,
+`DelaunayTriangulationInput`). Invalid input — wrong shape, non-numeric values,
+too few points, or degenerate configurations — raises
+`pydantic.ValidationError` at construction time.
+
+See the [API reference](../api/algorithms) for full signatures.