Merge pull request #17 from airallergy/documentation

airallergy · web-flow · commit faea11490fb8 · 2025-10-26T01:03:57.000Z
DOC: Add a basic documentation to be hosted on GitHub Pages
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml
@@ -0,0 +1,42 @@
+name: Publish Docs
+
+on:
+  push:
+    branches: main
+  workflow_dispatch:
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.5.*"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras --all-groups
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/publish_pypi.yml b/.github/workflows/publish_pypi.yml
@@ -0,0 +1,53 @@
+name: Publish PyPI
+
+on:
+  release:
+    types: published
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  upload-testpypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://test.pypi.org/p/sober
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  upload-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sober
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="doc/source/logo/sober_logo_white.svg">
-    <source media="(prefers-color-scheme: light)" srcset="doc/source/logo/sober_logo_black.svg">
-    <img alt="sober logo" src="doc/source/logo/sober_logo_black.svg" width="300">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo/sober_logo_black.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo/sober_logo_white.svg">
+    <img alt="sober logo" src="docs/assets/logo/sober_logo_black.svg" width="300">
 </picture>
 
 **sober** **o**ptimises **b**uilt **e**nvironment **r**obustly
diff --git a/docs/api/config.md b/docs/api/config.md
@@ -0,0 +1,3 @@
+# Config
+
+::: sober.config
diff --git a/docs/api/input.md b/docs/api/input.md
@@ -0,0 +1,3 @@
+# Input
+
+::: sober.input
diff --git a/docs/api/output.md b/docs/api/output.md
@@ -0,0 +1,3 @@
+# Output
+
+::: sober.output
diff --git a/docs/api/problem.md b/docs/api/problem.md
@@ -0,0 +1,3 @@
+# Problem
+
+::: sober.problem
diff --git a/docs/assets/logo/sober_logo_black.svg b/docs/assets/logo/sober_logo_black.svg
diff --git a/docs/assets/logo/sober_logo_white.svg b/docs/assets/logo/sober_logo_white.svg
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+<picture>
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo/sober_logo_black.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo/sober_logo_white.svg">
+    <img alt="sober logo" src="assets/logo/sober_logo_black.svg" width="300">
+</picture>
+
+**sober** **o**ptimises **b**uilt **e**nvironment **r**obustly
+
+---
+
+## Installation
+
+**sober** can be installed via either `conda`:
+
+```zsh
+conda install -c conda-forge sober
+```
+
+or `pip`:
+
+```zsh
+pip install sober
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,68 @@
+site_name: sober
+site_url: https://airallergy.github.io/sober/
+site_description: Documentation for sober
+site_author: Cheng Cui
+repo_url: https://github.com/airallergy/sober
+repo_name: airallergy/sober
+copyright: Copyright &copy; 2022 - 2025 Cheng Cui
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.sections
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/weather-hurricane-outline
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
+
+nav:
+  - Home: index.md
+  - API reference:
+      - Config: api/config.md
+      - Input: api/input.md
+      - Output: api/output.md
+      - Problem: api/problem.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [.]
+          options:
+            # General
+            show_bases: false
+            show_source: false
+            # Headings
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            # Members
+            filters:
+              - "!^_" # hide private members
+              - "!^__" # hide dunders
+            # Docstrings
+            docstring_style: numpy
+            docstring_section_style: spacy
+            merge_init_into_class: true
+            # Signatures
+            line_length: 88
+            overloads_only: true
+            separate_signature: true
+
+markdown_extensions:
+  - toc:
+      permalink: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -23,7 +23,14 @@ homepage = "https://github.com/airallergy/sober"
 repository = "https://github.com/airallergy/sober"
 
 [dependency-groups]
-dev = ["mypy~=1.12", "pytest-cov==5.*", "pytest==8.*", "ruff==0.11.*"]
+dev = [
+    "mkdocs-material==9.*",
+    "mkdocstrings[python]==0.30.*",
+    "mypy~=1.12",
+    "pytest-cov==5.*",
+    "pytest==8.*",
+    "ruff==0.11.*",
+]
 
 [tool.ruff.lint]
 select = [
diff --git a/sober/output.py b/sober/output.py
@@ -307,10 +307,6 @@ class ScriptCollector(_Collector):
         Optimisation constraint bounds.
     is_final : bool, default: `True`
         Whether the output is final and recorded.
-
-    Methods
-    -------
-    loads_kwargs
     """
 
     _RESERVED_KWARGS_KEYS: Final = frozenset(
diff --git a/sober/problem.py b/sober/problem.py
@@ -50,17 +50,12 @@ class Problem:
     noise_sample_kwargs : dict, optional
         Settings for sampling uncertain variables, including
 
-        +------------+-----------------+----------------------------------------+
         | Key        | Description     | Value type                             |
-        +============+=================+========================================+
+        |------------|-----------------|----------------------------------------|
         | `'mode'`   | Sampling mode   | `{'elementwise', 'cartesian', 'auto'}` |
-        +------------+-----------------+----------------------------------------+
         | `'size'`   | Sample size     | `int`                                  |
-        +------------+-----------------+----------------------------------------+
         | `'method'` | Sampling method | `{'random', 'latin hypercube'}`        |
-        +------------+-----------------+----------------------------------------+
         | `'seed'`   | Random seed     | `int`                                  |
-        +------------+-----------------+----------------------------------------+
 
         - If `'mode'='elementwise'`, `'size'` and `'method'` are mandatory.
         - If `'mode'='cartesian'`, all model inputs must be non-continuous variables,
@@ -71,14 +66,6 @@ class Problem:
         This is ignored if `removes_subdirs` is set to `True`.
     removes_subdirs : bool, default: `False`
         Whether to remove the subdirectories in the evaluation directory.
-
-    Methods
-    -------
-    run_random
-    run_latin_hypercube
-    run_exhaustive
-    run_nsga2
-    run_nsga3
     """
 
     __slots__ = (
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Problem`
	`2`	`+`
	`3`	`+::: sober.problem`