docs: introduce sphinx build, readthedocs, and docs workflow (#81)

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[docs]
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make clean && make html # SPHINXOPTS="-W --keep-going"
+
+    - name: Notice
+      run: |
+        echo "Documentation build successful!"
+        echo "After merging this PR, you can view the latest documentation at:"
+        echo "- Public docs: https://camtools.readthedocs.io/en/latest/"
+        echo "- Admin panel: https://app.readthedocs.org/projects/camtools/"

.gitignore

@@ -77,6 +77,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+.doctrees
+.buildinfo
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf

README.md

@@ -4,14 +4,20 @@
     <img alt="CamTools Logo" src="https://raw.githubusercontent.com/yxlao/camtools/main/camtools/assets/camtools_logo_light.png" width="360">
   </picture>
 </p>
+
 <h1 align="center">CamTools: Camera Tools for Computer Vision</h1>
 
+<p align="center">
+  <a href="https://camtools.readthedocs.io/"><strong>Docs</strong></a> |
+  <a href="https://github.com/yxlao/camtools"><strong>Repo</strong></a> |
+  <a href="#installation"><strong>Installation</strong></a>
+</p>
+
 [![Formatter](https://github.com/yxlao/camtools/actions/workflows/formatter.yml/badge.svg)](https://github.com/yxlao/camtools/actions/workflows/formatter.yml)
 [![Unit Test](https://github.com/yxlao/camtools/actions/workflows/unit_test.yml/badge.svg)](https://github.com/yxlao/camtools/actions/workflows/unit_test.yml)
 [![PyPI](https://github.com/yxlao/camtools/actions/workflows/pypi.yml/badge.svg)](https://github.com/yxlao/camtools/actions/workflows/pypi.yml)
-[![GitHub](https://img.shields.io/badge/GitHub-323940.svg?style=flat&logo=github&logoColor=959DA5)](https://github.com/yxlao/camtools)
-[![Gitee](https://img.shields.io/badge/Gitee-323940.svg?style=flat&logo=gitee&logoColor=959DA5)](https://gitee.com/yxlao/camtools)
 [![PyPI](https://img.shields.io/pypi/v/camtools?style=flat&label=PyPI&logo=PyPI&logoColor=959DA5&labelColor=323940&color=808080)](https://pypi.org/project/camtools)
+[![Docs](https://readthedocs.org/projects/camtools/badge/?version=latest)](https://camtools.readthedocs.io/en/latest/?badge=latest)
 
 CamTools is a collection of tools for handling cameras in computer vision. It
 can be used for plotting, converting, projecting, ray casting, and doing more
@@ -20,8 +26,13 @@ clear and easy-to-use APIs.
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yxlao/camtools/main/camtools/assets/camera_coordinates_dark.png">
-    <img alt="CamTools Logo" src="https://raw.githubusercontent.com/yxlao/camtools/main/camtools/assets/camera_coordinates_light.png" width="520">
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://raw.githubusercontent.com/yxlao/camtools/main/camtools/assets/camera_coordinates_dark.png">
+    <img
+      alt="CamTools Logo"
+      src="https://raw.githubusercontent.com/yxlao/camtools/main/camtools/assets/camera_coordinates_light.png"
+      width="520">
   </picture>
 </p>
 
@@ -251,6 +262,31 @@ the beginning of the README.
   [part 2](https://ksimek.github.io/2012/08/22/extrinsic/),
   and [part 3](https://ksimek.github.io/2013/08/13/intrinsic/).
 
+## Building Documentation
+
+To build and view the documentation locally:
+
+```bash
+# Install documentation dependencies
+pip install -e .[docs]
+
+# Build the documentation
+make -C docs clean && make -C docs html
+
+# (Optional) Build the documentation with warnings as errors
+make -C docs clean && make -C docs html SPHINXOPTS="-W --keep-going"
+
+# Start a local server to view the documentation
+python -m http.server 8000 --directory docs/_build/html
+```
+
+Then open your browser and navigate to `http://localhost:8000` to view the documentation.
+
+The documentation is also automatically built by GitHub Actions on pull requests and pushes to main. After merging to main, you can view:
+
+- Public documentation at https://camtools.readthedocs.io/en/latest/
+- Admin panel at https://app.readthedocs.org/projects/camtools/
+
 ## Contributing
 
 - Follow [Angular's commit message convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) for PRs.

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     = .
+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/api.rst

@@ -0,0 +1,26 @@
+API Reference
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   api/camera
+   api/colormap
+   api/convert
+   api/geometry
+   api/image
+   api/io
+   api/metric
+   api/normalize
+   api/project
+   api/raycast
+   api/render
+   api/solver
+   api/transform
+
+
+.. Not included in the docs website:
+..    api/artifact
+..    api/colmap
+..    api/sanity
+..    api/util

docs/api/camera.rst

@@ -0,0 +1,9 @@
+ct.camera
+=========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.camera
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/colormap.rst

@@ -0,0 +1,9 @@
+ct.colormap
+===========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.colormap
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/convert.rst

@@ -0,0 +1,9 @@
+ct.convert
+==========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.convert
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/geometry.rst

@@ -0,0 +1,9 @@
+ct.geometry
+===========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.geometry
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/image.rst

@@ -0,0 +1,9 @@
+ct.image
+========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.image
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/io.rst

@@ -0,0 +1,9 @@
+ct.io
+=======
+
+.. currentmodule:: ct
+
+.. automodule:: ct.io
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/metric.rst

@@ -0,0 +1,9 @@
+ct.metric
+=========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.metric
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/normalize.rst

@@ -0,0 +1,9 @@
+ct.normalize
+===========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.normalize
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/project.rst

@@ -0,0 +1,9 @@
+ct.project
+==========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.project
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/raycast.rst

@@ -0,0 +1,9 @@
+ct.raycast
+==========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.raycast
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/render.rst

@@ -0,0 +1,9 @@
+ct.render
+=========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.render
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/solver.rst

@@ -0,0 +1,9 @@
+ct.solver
+=========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.solver
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/transform.rst

@@ -0,0 +1,9 @@
+ct.transform
+===========
+
+.. currentmodule:: ct
+
+.. automodule:: ct.transform
+   :members:
+   :undoc-members:
+   :show-inheritance: