Skip to content

Commit 66427a1

Browse files
m2papierzm2papierz
committed
docs: add global Mermaid styling + fix RTD uv install
1 parent b33f146 commit 66427a1

5 files changed

Lines changed: 104 additions & 113 deletions

File tree

‎docs/_static/css/mermaid.css‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/* Mermaid diagrams: make them look great in RTD content column */
2+
div.mermaid {
3+
overflow-x: auto;
4+
padding: 0.75rem;
5+
border: 1px solid #e2e8f0;
6+
border-radius: 0.5rem;
7+
background: #ffffff;
8+
}
9+
10+
/* SVG never overflows the content width */
11+
div.mermaid svg {
12+
max-width: 100%;
13+
height: auto;
14+
}

‎docs/concepts/overview.md‎

Lines changed: 12 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -17,21 +17,6 @@ devqubit treats each execution as a **run** — a complete, tracked experiment w
1717
When you wrap a backend with `run.wrap()`, devqubit intercepts executions and automatically captures circuits, device state, and results. Manual logging (`log_param`, `log_metric`) is stored alongside. Everything flows into a content-addressed store for deduplication and integrity, with queryable metadata in a registry.
1818

1919
```mermaid
20-
%%{init:{
21-
"theme":"base",
22-
"flowchart":{"curve":"basis","nodeSpacing":34,"rankSpacing":44,"htmlLabels":true},
23-
"themeVariables":{
24-
"fontFamily":"ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica, Arial, sans-serif",
25-
"fontSize":"14px",
26-
"background":"#ffffff",
27-
"textColor":"#0f172a",
28-
"lineColor":"#94a3b8",
29-
"clusterBkg":"#f8fafc",
30-
"clusterBorder":"#cbd5e1",
31-
"edgeLabelBackground":"#ffffff"
32-
}
33-
}}%%
34-
3520
flowchart TB
3621
subgraph USER["User Code"]
3722
direction TB
@@ -77,19 +62,17 @@ flowchart TB
7762
REG --> TOOLS
7863
STORE --> TOOLS
7964
80-
linkStyle default stroke:#94a3b8,stroke-width:1.4
65+
linkStyle default stroke-width:1.4
8166
82-
%% Subgraphy jako “sekcje” + białe karty w środku
83-
style USER fill:#eff6ff,stroke:#2563eb,stroke-width:1.6,color:#0f172a
84-
style CAPTURE fill:#fffbeb,stroke:#d97706,stroke-width:1.6,color:#0f172a
85-
style PERSIST fill:#ecfdf5,stroke:#059669,stroke-width:1.6,color:#064e3b
86-
style TOOLS fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.6,color:#3b0764
67+
style USER fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5,color:#0f172a
68+
style CAPTURE fill:#fffbeb,stroke:#f59e0b,stroke-width:1.5,color:#0f172a
69+
style PERSIST fill:#ecfdf5,stroke:#10b981,stroke-width:1.5,color:#064e3b
70+
style TOOLS fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.5,color:#3b0764
8771
88-
classDef card fill:#ffffff,stroke:#cbd5e1,stroke-width:1.2,color:#0f172a;
72+
classDef card fill:#ffffff,stroke:#cbd5e1,stroke-width:1.1,color:#0f172a;
8973
class TRACK,LOG,WRAP,EXEC,CAP_PRG,CAP_DEV,CAP_RES,ENV,RR,DIFF,VERIFY card
90-
classDef pill fill:#ffffff,stroke:#cbd5e1,stroke-width:1.2,color:#0f172a;
74+
classDef pill fill:#ffffff,stroke:#cbd5e1,stroke-width:1.1,color:#0f172a;
9175
class STORE,REG pill
92-
9376
```
9477

9578
## What Is Persisted Where?
@@ -117,21 +100,6 @@ A run captures everything about a single experiment execution. Run records follo
117100
## Run Lifecycle
118101

119102
```mermaid
120-
%%{init:{
121-
"theme":"base",
122-
"flowchart":{"curve":"basis","nodeSpacing":34,"rankSpacing":40,"htmlLabels":true},
123-
"themeVariables":{
124-
"fontFamily":"ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica, Arial, sans-serif",
125-
"fontSize":"14px",
126-
"background":"#ffffff",
127-
"textColor":"#0f172a",
128-
"lineColor":"#94a3b8",
129-
"clusterBkg":"#f8fafc",
130-
"clusterBorder":"#cbd5e1",
131-
"edgeLabelBackground":"#ffffff"
132-
}
133-
}}%%
134-
135103
flowchart LR
136104
S((" ")) --> R[RUNNING]
137105
R -->|success| F[FINISHED]
@@ -141,13 +109,13 @@ flowchart LR
141109
X --> E
142110
K --> E
143111
144-
linkStyle default stroke:#94a3b8,stroke-width:1.4
112+
linkStyle default stroke-width:1.4
145113
146114
classDef ghost fill:#334155,stroke:#334155,color:#334155;
147-
classDef running fill:#eff6ff,stroke:#2563eb,stroke-width:1.6,color:#0f172a;
148-
classDef finished fill:#ecfdf5,stroke:#059669,stroke-width:1.6,color:#064e3b;
149-
classDef failed fill:#fee2e2,stroke:#dc2626,stroke-width:1.6,color:#7f1d1d;
150-
classDef killed fill:#fffbeb,stroke:#d97706,stroke-width:1.6,color:#7c2d12;
115+
classDef running fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5,color:#0f172a;
116+
classDef finished fill:#ecfdf5,stroke:#10b981,stroke-width:1.5,color:#064e3b;
117+
classDef failed fill:#fee2e2,stroke:#ef4444,stroke-width:1.5,color:#7f1d1d;
118+
classDef killed fill:#fffbeb,stroke:#f59e0b,stroke-width:1.5,color:#7c2d12;
151119
152120
class S,E ghost
153121
class R running

‎docs/concepts/uec.md‎

Lines changed: 9 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,6 @@ Quantum experiments depend on **programs**, **devices**, **execution settings**,
1010
## Envelope at a Glance
1111

1212
```mermaid
13-
%%{init:{
14-
"theme":"base",
15-
"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":44,"htmlLabels":true},
16-
"themeVariables":{
17-
"fontFamily":"ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica, Arial, sans-serif",
18-
"fontSize":"14px",
19-
"background":"#ffffff",
20-
"textColor":"#0f172a",
21-
"lineColor":"#94a3b8",
22-
"clusterBkg":"#f8fafc",
23-
"clusterBorder":"#cbd5e1",
24-
"edgeLabelBackground":"#ffffff"
25-
}
26-
}}%%
27-
2813
flowchart TB
2914
subgraph ENV["ExecutionEnvelope"]
3015
direction TB
@@ -59,18 +44,17 @@ flowchart TB
5944
DEV -.->|raw_properties_ref| A3
6045
RES -.->|raw_result_ref| A4
6146
62-
%% Linki: delikatniejsze i równe
63-
linkStyle default stroke:#94a3b8,stroke-width:1.4
47+
linkStyle default stroke-width:1.4
48+
49+
classDef grpBlue fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5,color:#0f172a;
50+
classDef grpAmber fill:#fffbeb,stroke:#f59e0b,stroke-width:1.5,color:#0f172a;
51+
classDef cardBlue fill:#dbeafe,stroke:#60a5fa,stroke-width:1.2,color:#0f172a;
52+
classDef cardGreen fill:#ecfdf5,stroke:#34d399,stroke-width:1.2,color:#064e3b;
53+
classDef artifact fill:#fff7ed,stroke:#fb923c,stroke-width:1.2,color:#7c2d12;
6454
65-
%% Klasy zamiast wielu style-line
66-
classDef grpBlue fill:#eff6ff,stroke:#2563eb,stroke-width:1.6,color:#0f172a;
67-
classDef grpAmber fill:#fffbeb,stroke:#d97706,stroke-width:1.6,color:#0f172a;
68-
classDef cardBlue fill:#dbeafe,stroke:#3b82f6,stroke-width:1.4,color:#0f172a;
69-
classDef cardGreen fill:#ecfdf5,stroke:#10b981,stroke-width:1.4,color:#064e3b;
70-
classDef artifact fill:#fff7ed,stroke:#f59e0b,stroke-width:1.4,color:#7c2d12;
55+
style ENV fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5,color:#0f172a
56+
style STORE fill:#fffbeb,stroke:#f59e0b,stroke-width:1.5,color:#0f172a
7157
72-
class ENV grpBlue
73-
class STORE grpAmber
7458
class META cardBlue
7559
class PROD,PROG,DEV,EXEC,RES cardGreen
7660
class A1,A2,A3,A4 artifact

‎docs/conf.py‎

Lines changed: 69 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,63 @@
11
# Configuration file for Sphinx.
2-
# See Sphinx docs for details:
32
# https://www.sphinx-doc.org/en/master/usage/configuration.html
43

54
from __future__ import annotations
65

6+
import json
77
import tomllib
88
from datetime import date
99
from pathlib import Path
1010

1111

12+
# -- Project information -----------------------------------------------------
13+
1214
project = "devqubit"
1315
author = "devqubit"
1416
copyright = f"{date.today().year}, {author}"
1517

18+
# Try to read version from pyproject.toml (optional)
19+
ROOT = Path(__file__).resolve().parents[1]
20+
_pyproject = ROOT / "pyproject.toml"
21+
release = ""
22+
version = ""
23+
if _pyproject.exists():
24+
try:
25+
data = tomllib.loads(_pyproject.read_text(encoding="utf-8"))
26+
release = str(data.get("project", {}).get("version", "")) or ""
27+
version = release
28+
except Exception:
29+
release = ""
30+
version = ""
1631

17-
def _version_from_pyproject() -> str | None:
18-
"""Reads version from repository's pyproject.toml."""
19-
20-
repo_root = Path(__file__).resolve().parents[1]
21-
pyproject_path = repo_root / "pyproject.toml"
22-
if not pyproject_path.exists():
23-
return None
24-
25-
data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
26-
27-
# PEP 621
28-
proj = data.get("project", {})
29-
v = proj.get("version")
30-
if isinstance(v, str) and v.strip():
31-
return v.strip()
32-
33-
# Poetry fallback (optional)
34-
poetry = data.get("tool", {}).get("poetry", {})
35-
v = poetry.get("version")
36-
if isinstance(v, str) and v.strip():
37-
return v.strip()
38-
39-
return None
4032

41-
42-
# Read package version (robust fallback)
43-
release = _version_from_pyproject() or "0.0.0"
44-
version = release.split("+")[0]
33+
# -- General configuration ---------------------------------------------------
4534

4635
extensions = [
36+
"sphinx.ext.intersphinx",
4737
"myst_parser",
4838
"sphinxcontrib.mermaid",
49-
"sphinx.ext.intersphinx",
50-
"sphinx.ext.autosectionlabel",
5139
]
5240

53-
# Make section labels unique across pages
54-
autosectionlabel_prefix_document = True
41+
templates_path = ["_templates"]
42+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
43+
44+
45+
# -- MyST (Markdown) ---------------------------------------------------------
5546

56-
# MyST (Markdown) configuration
5747
myst_enable_extensions = [
5848
"colon_fence",
59-
"deflist",
60-
"tasklist",
6149
]
62-
myst_heading_anchors = 3 # auto-generate anchors for h1-h3
50+
myst_fence_as_directive = {
51+
"mermaid",
52+
}
6353

64-
# Treat ```mermaid fences as Sphinx directives
65-
myst_fence_as_directive = ["mermaid"]
6654

67-
templates_path: list[str] = []
68-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
55+
# -- Options for HTML output -------------------------------------------------
6956

70-
# HTML output
71-
html_theme = "sphinx_rtd_theme"
72-
html_static_path: list[str] = []
57+
html_static_path = ["_static"]
58+
html_css_files = [
59+
"css/mermaid.css",
60+
]
7361

7462
# Show "Edit on GitHub"
7563
html_context = {
@@ -80,6 +68,44 @@ def _version_from_pyproject() -> str | None:
8068
"conf_py_path": "/docs/",
8169
}
8270

71+
72+
# -- Intersphinx -------------------------------------------------------------
73+
8374
intersphinx_mapping = {
8475
"python": ("https://docs.python.org/3", None),
8576
}
77+
78+
79+
# -- Mermaid (sphinxcontrib-mermaid) ----------------------------------------
80+
81+
mermaid_output_format = "raw" # keep diagrams interactive in HTML
82+
83+
# Nice UX on ReadTheDocs
84+
mermaid_d3_zoom = True
85+
mermaid_fullscreen = True
86+
mermaid_fullscreen_button_opacity = 35
87+
88+
# Global Mermaid "house style" (applies to all diagrams)
89+
_mermaid_config = {
90+
"startOnLoad": True,
91+
"securityLevel": "loose",
92+
"theme": "base",
93+
"flowchart": {
94+
"curve": "basis",
95+
"nodeSpacing": 36,
96+
"rankSpacing": 44,
97+
"htmlLabels": True,
98+
},
99+
"themeVariables": {
100+
"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica, Arial, sans-serif",
101+
"fontSize": "14px",
102+
"background": "#ffffff",
103+
"textColor": "#0f172a",
104+
"lineColor": "#94a3b8",
105+
"clusterBkg": "#f8fafc",
106+
"clusterBorder": "#cbd5e1",
107+
"edgeLabelBackground": "#ffffff",
108+
},
109+
}
110+
111+
mermaid_init_js = f"mermaid.initialize({json.dumps(_mermaid_config)});"

‎docs/make.bat‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
\
21
@ECHO OFF
32

43
REM Minimal make.bat for Sphinx documentation

0 commit comments

Comments
 (0)