Implement setup for building API documentation with mkdocs and GitHub pages

.github/workflows/ci.yml

@@ -70,7 +70,4 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Build package
-        run: uv run python -m build
-
-      - name: Check distribution
-        run: uv run twine check dist/*
+        run: uv build

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          sparse-checkout: |
+            docs
+            src
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: 3.12
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install the project
+        run: uv sync --dev --group docs
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache 
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest tests --cov=fluree_py --cov-report=html --cov-report=term-missing
+
+      - name: Build and upload documentation
+        run: uv run mkdocs gh-deploy --force

docs/css/extra.css

@@ -0,0 +1,27 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

docs/index.md

@@ -0,0 +1,21 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+- `mkdocs new [dir-name]` - Create a new project.
+- `mkdocs serve` - Start the live-reloading docs server.
+- `mkdocs build` - Build the documentation site.
+- `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+```
+mkdocs.yml    # The configuration file.
+docs/
+    index.md  # The documentation homepage.
+    ...       # Other markdown pages, images and other files.
+```
+
+## Project Overview

mkdocs.yml

@@ -0,0 +1,138 @@
+site_name: "fluree-py"
+site_description: "A Python client for Flur.ee's HTTP API"
+site_url: "https://crcresearch.github.io/fluree-py"
+repo_url: "https://github.com/crcresearch/fluree-py"
+repo_name: "crcresearch/fluree-py"
+site_dir: "site"
+watch: [mkdocs.yml, README.md, src/fluree_py]
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+plugins:
+- search
+- callouts
+- literate-nav:
+    nav_file: SUMMARY.md
+- autorefs
+- section-index
+- git-revision-date-localized:
+    enabled: !ENV [DEPLOY, false]
+    enable_creation_date: true
+    type: timeago
+- coverage:
+    page_path: coverage  # default
+    html_report_dir: htmlcov  # default
+- api-autonav:
+    modules: ['src/fluree_py']
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        inventories:
+        - https://docs.python.org/3/objects.inv
+        options:
+          # General
+          find_stubs_package: true
+          show_bases: true
+          show_source: false
+          extensions:
+          - griffe_generics
+          - griffe_warnings_deprecated
+          - griffe_modernized_annotations
+          - griffe_pydantic:
+              schema: true
+          # Headings
+          heading_level: 1
+          show_root_heading: true
+          show_root_full_path: false
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
+          # Members
+          summary: true
+          # Docstrings
+          docstring_options:
+            ignore_init_summary: true
+          docstring_section_style: list
+          merge_init_into_class: true
+          # Signatures
+          line_length: 120
+          separate_signature: true
+          show_signature_annotations: true
+          show_overloads: true
+          signature_crossrefs: true
+          unwrap_annotated: false
+theme:
+  name: material
+  features:
+  - announce.dismiss
+  - content.action.edit
+  - content.action.view
+  - content.code.annotate
+  - content.code.copy
+  - content.tooltips
+  - navigation.footer
+  - navigation.instant.preview
+  - navigation.path
+  - navigation.sections
+  - navigation.tabs
+  - navigation.tabs.sticky
+  - navigation.top
+  - search.highlight
+  - search.suggest
+  - toc.follow
+  icon:
+    repo: fontawesome/brands/github 
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: purple
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: lime
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
+extra_css:
+- css/extra.css
+
+markdown_extensions:
+  - attr_list
+  - md_in_html
+  - nl2br
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: "¤"
+
+nav:
+  - Home: index.md
+  - Coverage report: coverage.md
+
+extra:
+  social:
+  - icon: fontawesome/brands/python
+    link: https://pypi.org/project/fluree-py/

pyproject.toml

@@ -3,32 +3,42 @@ name = "fluree-py"
 version = "0.1.0"
 description = "Add your description here"
 readme = "README.md"
-authors = [
-    { name = "James Sweet", email = "[email protected]" }
-]
+authors = [{ name = "James Sweet", email = "[email protected]" }]
 requires-python = ">=3.11"
-dependencies = [
-    "httpx>=0.28.1",
-    "pydantic>=2.10.6",
-]
+dependencies = ["httpx>=0.28.1", "pydantic>=2.10.6"]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-    "polyfactory>=2.20.0",
-    "pytest-icdiff>=0.9",
-    "pytest-sugar>=1.0.0",
-    "pytest>=8.3.5",
-    "respx>=0.22.0",
-    "testcontainers[generic]>=4.9.2",
-    "hypothesis>=6.130.5",
-    "pytest-cov>=6.0.0",
+  "polyfactory>=2.20.0",
+  "pytest-icdiff>=0.9",
+  "pytest-sugar>=1.0.0",
+  "pytest>=8.3.5",
+  "respx>=0.22.0",
+  "testcontainers[generic]>=4.9.2",
+  "hypothesis>=6.130.5",
+  "pytest-cov>=6.0.0",
 ]
-lint = [
-    "ruff>=0.11.2",
+lint = ["ruff>=0.11.2"]
+docs = [
+  "mkdocs>=1.6.1",
+  "mkdocs-material>=9.6.10",
+  "mkdocstrings[python]>=0.29.1",
+  "mkdocs-coverage>=1.1.0",
+  "mkdocs-section-index>=0.3.9",
+  "mkdocs-git-revision-date-localized-plugin>=1.4.5",
+  "griffe-pydantic>=1.1.4",
+  "griffe-warnings-deprecated>=1.1.0",
+  "griffe-generics>=1.0.13",
+  "griffe-inherited-method-crossrefs>=0.0.1.4",
+  "griffe-modernized-annotations>=1.0.8",
+  "markdown-callouts>=0.4.0",
+  "mkdocs-api-autonav>=0.2.1",
+  "mkdocs-literate-nav>=0.6.2",
+  "mkdocs-callouts>=1.16.0",
 ]
 
 [tool.uv]
@@ -41,9 +51,7 @@ addopts = "--import-mode=importlib --verbose"
 packages = ["src/fluree_py"]
 
 [tool.hatch.build.targets.sdist]
-include = [
-    "src/fluree_py/**/*.py",
-]
+include = ["src/fluree_py/**/*.py"]
 
 [tool.hatch.metadata]
 allow-direct-references = true

src/fluree_py/client.py

@@ -6,7 +6,10 @@
 
 @dataclass(frozen=True, kw_only=True)
 class FlureeClient:
+    """Client for interacting with Fluree databases."""
+
     base_url: str
 
     def with_ledger(self, ledger: str) -> SupportsLedgerOperations:
+        """Select a ledger to operate on."""
         return LedgerSelected(base_url=self.base_url, ledger=ledger)

src/fluree_py/ledger/builder/create.py

@@ -19,15 +19,19 @@ class CreateReadyToCommitImpl(
     CommitableMixin["CreateReadyToCommitImpl"],
     CreateReadyToCommit,
 ):
+    """Implementation of a create operation ready to be committed."""
+
     endpoint: str
     ledger: str
     data: JsonObject | JsonArray | None
     context: dict[str, Any] | None = None
 
     def get_url(self) -> str:
+        """Get the endpoint URL for the create operation."""
         return self.endpoint
 
     def build_request_payload(self) -> dict[str, Any]:
+        """Build the request payload for the create operation."""
         result: dict[str, Any] = {}
         if self.context:
             result["@context"] = self.context
@@ -41,6 +45,8 @@ class CreateBuilderImpl(
     WithInsertMixin[CreateReadyToCommitImpl],
     CreateBuilder,
 ):
+    """Implementation of a create operation builder."""
+
     endpoint: str
     ledger: str
     data: JsonObject | JsonArray | None = None