Merge pull request #26 from gtfierro/docs

Add Sphinx docs and Pages deployment workflow

Author: gtfierro

.github/workflows/pages.yml

@@ -0,0 +1,74 @@
+# Deploy Sphinx docs to GitHub Pages using the builddocs helper.
+name: Deploy docs to Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libssl-dev pkg-config
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Sync docs environment
+        working-directory: docs
+        env:
+          UV_SYSTEM_RESOLVE: "0"
+        run: uv sync --project .
+
+      - name: Install ontoenv into docs venv
+        working-directory: docs
+        env:
+          UV_SYSTEM_RESOLVE: "0"
+        run: uv pip install --project . -e ../python
+
+      - name: Build Sphinx HTML
+        working-directory: docs
+        env:
+          UV_SYSTEM_RESOLVE: "0"
+        run: uv run --project . sphinx-build -M html . _build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,2 +1,6 @@
 /target
 .ontoenv
+docs/_build/
+docs/_doctrees/
+docs/.venv/
+.uv-cache/

builddocs

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+export UV_CACHE_DIR="${UV_CACHE_DIR:-"$ROOT/.uv-cache"}"
+export UV_SYSTEM_RESOLVE="${UV_SYSTEM_RESOLVE:-0}"
+
+pushd "$ROOT/docs"
+MODE="${1:-html}"
+if [[ "$MODE" != "html" && "$MODE" != "llms" ]]; then
+  echo "Usage: $0 [html|llms]" >&2
+  exit 64
+fi
+
+# Ensure the docs environment is provisioned.
+uv sync --project .
+
+# Install the Python extension into the docs venv so autodoc can import it.
+uv pip install --project . -e "$ROOT/python"
+
+if [[ "$MODE" == "html" ]]; then
+  uv run --project . sphinx-build -M html . _build
+else
+  uv run --project . sphinx-build -M text . _build
+  find _build/text -name '*.txt' -print | sort | xargs cat > _build/llms.txt
+  echo "Wrote _build/llms.txt"
+fi
+popd

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal Makefile for Sphinx documentation
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html llms
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"
+
+# Produce a single concatenated text file for LLM ingestion.
+llms:
+	@$(SPHINXBUILD) -M text "$(SOURCEDIR)" "$(BUILDDIR)"
+	@find "$(BUILDDIR)/text" -name '*.txt' -print | sort | xargs cat > "$(BUILDDIR)/llms.txt"
+	@echo "Wrote $(BUILDDIR)/llms.txt"
+
+clean:
+	rm -rf "$(BUILDDIR)"

docs/_static/.gitkeep

@@ -0,0 +1 @@
+

docs/_templates/.gitkeep

@@ -0,0 +1 @@
+

docs/cli/index.rst

@@ -0,0 +1,33 @@
+CLI Usage
+=========
+
+The ``ontoenv`` CLI wraps the Rust core with commands for discovering and materializing ontology imports.
+
+Install
+-------
+
+.. code-block:: bash
+
+   cargo install ontoenv-cli
+   # or from the workspace:
+   cargo build -p ontoenv-cli --release
+   ./target/release/ontoenv --help
+
+Common tasks
+------------
+
+- ``ontoenv init`` — create a new ontology environment in the current directory.
+- ``ontoenv add <path-or-iri>`` — register an ontology; optionally fetch its imports.
+- ``ontoenv update`` — refresh cached ontologies.
+- ``ontoenv dump`` — export the current environment for inspection.
+
+Reference
+---------
+
+Start by embedding the CLI help output as the reference page. Replace this block once you settle on a stable command set:
+
+.. code-block:: text
+
+   $ ontoenv --help
+   (paste the generated help text here)
+

docs/conf.py

@@ -0,0 +1,68 @@
+"""Sphinx configuration for the OntoEnv project."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - fallback for older interpreters
+    import tomli as tomllib  # type: ignore
+
+
+ROOT = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = ROOT
+PYTHON_SRC = PROJECT_ROOT / "python"
+
+# Ensure the Python bindings are importable when building docs locally.
+sys.path.insert(0, str(PYTHON_SRC))
+
+
+def _read_version() -> str:
+    """Read the workspace version from Cargo.toml for a single source of truth."""
+    cargo_toml = PROJECT_ROOT / "Cargo.toml"
+    try:
+        with cargo_toml.open("rb") as fh:
+            cargo = tomllib.load(fh)
+        return cargo.get("workspace", {}).get("package", {}).get("version", "0.0.0")
+    except Exception:
+        return "0.0.0"
+
+
+project = "OntoEnv"
+author = "OntoEnv developers"
+release = _read_version()
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+]
+
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_mock_imports = ["rdflib", "oxrdflib"]
+
+templates_path = ["_templates"]
+exclude_patterns: list[str] = [
+    "_build",
+    "_doctrees",
+    "Thumbs.db",
+    ".DS_Store",
+    ".venv",
+    ".venv/**",
+]
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_title = "OntoEnv Documentation"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", {}),
+    "rdflib": ("https://rdflib.readthedocs.io/en/stable", {}),
+}

docs/getting-started.rst

@@ -0,0 +1,65 @@
+Getting Started
+===============
+
+This section gives you a minimal checklist to build the documentation locally and wire it into your workflows.
+
+Install doc tooling with ``uv``
+----------------------------------------
+
+The docs have their own ``docs/pyproject.toml``. Create the env and install requirements with ``uv``:
+
+.. code-block:: bash
+
+   cd docs
+   uv sync            # creates docs/.venv and installs Sphinx + Furo
+
+If you prefer to reuse an existing environment, you can instead run ``uv pip install -r docs/requirements.txt``.
+
+Build the docs locally
+----------------------
+
+.. code-block:: bash
+
+   cd docs
+   uv run sphinx-build -M html . _build
+   open _build/html/index.html
+
+Or just run the helper from the repository root (it syncs deps, builds the extension, and renders HTML):
+
+.. code-block:: bash
+
+   ./builddocs
+
+Need a single text file for LLM ingestion? Use the alternate target:
+
+.. code-block:: bash
+
+   ./builddocs llms   # writes docs/_build/llms.txt
+
+Python package in editable mode
+-------------------------------
+
+To build the extension module so ``autodoc`` can import ``ontoenv``:
+
+.. code-block:: bash
+
+   cd python
+   uv run maturin develop
+
+CLI binary
+----------
+
+You can install the Rust CLI from crates.io or build it from the workspace:
+
+.. code-block:: bash
+
+   cargo install ontoenv-cli           # pulls the published binary
+   # or, from the workspace:
+   cargo build -p ontoenv-cli --release
+
+Publishing to GitHub Pages
+--------------------------
+
+- Build with ``uv run sphinx-build -M html . _build`` (or from CI).  
+- Publish the contents of ``docs/_build/html`` to your Pages branch (e.g., ``gh-pages``) or configure Pages to read from ``docs`` if you use ``sphinx-build -M dirhtml``.  
+- Remember to set the Pages source to ``/docs`` or the dedicated branch when you push to GitHub.

docs/index.rst

@@ -0,0 +1,13 @@
+OntoEnv Documentation
+=====================
+
+`OntoEnv` is a lightweight environment manager for RDF ontologies. The project ships a Rust core, a Python package, and a CLI so you can fetch, inspect, and reuse ontology imports from scripts or the command line.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   getting-started
+   python-api/index
+   cli/index
+