Skip to content

Commit f672fab

Browse files
KiguliKiguli
committed
Add Sphinx documentation site with Furo theme
Includes installation guide, quick start tutorial, examples gallery, and hand-written API reference for all barrier certificate functions. GitHub Actions workflow for automatic deployment to GitHub Pages.
1 parent ace7389 commit f672fab

File tree

15 files changed

+1346
-0
lines changed

15 files changed

+1346
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.10"
26+
27+
- uses: actions/cache@v4
28+
with:
29+
path: ~/.cache/pip
30+
key: ${{ runner.os }}-pip-docs-${{ hashFiles('requirements.txt', 'docs/requirements.txt') }}
31+
restore-keys: |
32+
${{ runner.os }}-pip-docs-
33+
34+
- name: Install project dependencies
35+
run: pip install -r requirements.txt
36+
37+
- name: Install docs dependencies
38+
run: pip install -r docs/requirements.txt
39+
40+
- name: Build HTML docs
41+
run: cd docs && make html
42+
43+
- name: Upload pages artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: docs/_build/html
47+
48+
deploy:
49+
runs-on: ubuntu-latest
50+
needs: build
51+
environment:
52+
name: github-pages
53+
steps:
54+
- name: Deploy to GitHub Pages
55+
uses: actions/deploy-pages@v4

‎docs/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
3+
# You can set these variables from the command line, and also
4+
# from the environment for the first two.
5+
SPHINXOPTS ?=
6+
SPHINXBUILD ?= sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/custom.css‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/* Custom styles for PRoTECT documentation */
2+
3+
/* === Code Blocks === */
4+
pre {
5+
font-size: 0.85em;
6+
border-left: 3px solid var(--color-brand-primary);
7+
border-radius: 0 4px 4px 0;
8+
}
9+
10+
code.literal {
11+
padding: 1px 4px;
12+
}
13+
14+
/* === Section headings === */
15+
.content h2 {
16+
padding-left: 0.6rem;
17+
border-left: 3px solid var(--color-brand-primary);
18+
}
19+
20+
/* === Card styling === */
21+
.sd-card {
22+
transition: box-shadow 0.2s ease, transform 0.15s ease;
23+
border-top: 2px solid transparent;
24+
}
25+
26+
.sd-card:hover {
27+
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
28+
transform: translateY(-2px);
29+
border-top-color: var(--color-brand-primary);
30+
}
31+
32+
/* === Tables === */
33+
table.docutils td:last-child {
34+
font-weight: 600;
35+
color: var(--color-brand-primary);
36+
}
37+
38+
table.docutils tbody tr:nth-child(even) {
39+
background-color: var(--color-background-secondary);
40+
}
41+
42+
table.docutils thead th {
43+
background-color: var(--color-brand-primary);
44+
color: white;
45+
font-weight: 600;
46+
}
47+
48+
/* === Admonition accents === */
49+
.admonition.note {
50+
border-left-color: var(--color-brand-primary);
51+
}
52+
53+
.admonition.warning {
54+
border-left-color: #ff9800;
55+
}
56+
57+
.admonition.tip {
58+
border-left-color: #4caf50;
59+
}
60+
61+
/* === Horizontal rules === */
62+
hr {
63+
margin: 2.5rem 0;
64+
border: none;
65+
border-top: 2px solid var(--color-brand-primary);
66+
opacity: 0.2;
67+
}
68+
69+
/* === Sidebar logo === */
70+
.sidebar-brand img {
71+
max-height: 40px;
72+
}
73+
74+
/* === Hero accent bar === */
75+
.page-content > .content > section:first-child > p:first-of-type {
76+
font-size: 1.15em;
77+
color: var(--color-foreground-secondary);
78+
}
79+
80+
/* === Badge polish === */
81+
.sd-badge {
82+
font-weight: 600;
83+
letter-spacing: 0.02em;
84+
}
85+
86+
/* === Scrollbar === */
87+
::-webkit-scrollbar {
88+
width: 8px;
89+
}
90+
91+
::-webkit-scrollbar-thumb {
92+
background: var(--color-brand-primary);
93+
border-radius: 4px;
94+
opacity: 0.5;
95+
}
96+
97+
::-webkit-scrollbar-thumb:hover {
98+
opacity: 0.8;
99+
}
100+
101+
::-webkit-scrollbar-track {
102+
background: var(--color-background-secondary);
103+
}
104+
105+
/* === Dark mode adjustments === */
106+
body[data-theme="dark"] table.docutils td:last-child {
107+
color: var(--color-brand-content);
108+
}
109+
110+
body[data-theme="dark"] table.docutils thead th {
111+
background-color: #1a3a7a;
112+
}
113+
114+
body[data-theme="dark"] .sd-card:hover {
115+
border-top-color: var(--color-brand-content);
116+
}

‎docs/api/ct_ds.rst‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
Continuous-Time Deterministic (ct-DS)
2+
======================================
3+
4+
Functions for computing barrier certificates for continuous-time deterministic
5+
systems over an infinite time horizon using Lie derivative conditions.
6+
7+
``ct_DS``
8+
---------
9+
10+
.. code-block:: python
11+
12+
from src.functions.ct_DS import ct_DS
13+
14+
result = ct_DS(b_degree, dim, L_initial, U_initial, L_unsafe, U_unsafe,
15+
L_space, U_space, x, f, solver="mosek", gam=None, lam=None,
16+
l_degree=None)
17+
18+
**Parameters:**
19+
20+
.. list-table::
21+
:widths: 20 15 65
22+
:header-rows: 1
23+
24+
* - Parameter
25+
- Type
26+
- Description
27+
* - ``b_degree``
28+
- int
29+
- Degree of the barrier polynomial.
30+
* - ``dim``
31+
- int
32+
- Dimension of the state space.
33+
* - ``L_initial``
34+
- np.ndarray
35+
- Lower bounds of the initial set. Shape: ``(dim,)``.
36+
* - ``U_initial``
37+
- np.ndarray
38+
- Upper bounds of the initial set. Shape: ``(dim,)``.
39+
* - ``L_unsafe``
40+
- np.ndarray
41+
- Lower bounds of unsafe set(s). Shape: ``(n_regions, dim)``.
42+
* - ``U_unsafe``
43+
- np.ndarray
44+
- Upper bounds of unsafe set(s). Shape: ``(n_regions, dim)``.
45+
* - ``L_space``
46+
- np.ndarray
47+
- Lower bounds of the state space. Shape: ``(dim,)``.
48+
* - ``U_space``
49+
- np.ndarray
50+
- Upper bounds of the state space. Shape: ``(dim,)``.
51+
* - ``x``
52+
- tuple
53+
- SymPy symbols for state variables, e.g. ``sp.symbols('x1:3')``.
54+
* - ``f``
55+
- np.ndarray
56+
- Array of SymPy expressions defining the dynamics :math:`\dot{x} = f(x)`.
57+
* - ``solver``
58+
- str
59+
- ``"mosek"`` (default) or ``"cvxopt"``.
60+
* - ``gam``
61+
- float or None
62+
- Fixed value for :math:`\gamma`. If ``None``, determined by the solver.
63+
* - ``lam``
64+
- float or None
65+
- Fixed value for :math:`\lambda`. If ``None``, determined by the solver.
66+
* - ``l_degree``
67+
- int or None
68+
- Degree of Lagrangian multipliers. Defaults to ``b_degree``.
69+
70+
**Returns:** ``dict`` with keys ``b_degree``, ``Barrier``, ``gamma``, ``lambda``, ``solver_status``, or ``None`` if infeasible.
71+
72+
----
73+
74+
``parallel_ct_DS``
75+
------------------
76+
77+
.. code-block:: python
78+
79+
from src.functions.parallel_ct_DS import parallel_ct_DS
80+
81+
result = parallel_ct_DS(b_degree, dim, L_initial, U_initial, L_unsafe,
82+
U_unsafe, L_space, U_space, x, f, solver="mosek",
83+
gam=None, lam=None, l_degree=None)
84+
85+
Searches barrier polynomial degrees 2, 4, ..., ``b_degree`` in parallel.
86+
Parameters are identical to ``ct_DS`` except ``b_degree`` is the **maximum**
87+
degree to search.
88+
89+
.. note::
90+
91+
Must be called inside ``if __name__ == '__main__':`` due to Python multiprocessing.
92+
93+
**Returns:** The result ``dict`` from the first successful degree, or ``None``.

0 commit comments

Comments
 (0)