Skip to content

Commit 3bc9b76

Browse files
mbruknermbrukner
authored
Pr/sphinx docs (#129)
Adds Sphinx based documentation to the project. --------- Signed-off-by: Matthias Brukner <mbrukner@gmail.com>
1 parent 4974134 commit 3bc9b76

20 files changed

Lines changed: 2840 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Build & Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ["sphinx-docs/**"]
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- uses: actions/setup-python@v5
25+
with:
26+
python-version: "3.12"
27+
28+
- name: Install dependencies
29+
run: pip install -r sphinx-docs/requirements.txt
30+
31+
- name: Build HTML
32+
run: sphinx-build -b html sphinx-docs sphinx-docs/_build/html
33+
34+
- name: Upload artifact
35+
uses: actions/upload-pages-artifact@v3
36+
with:
37+
path: sphinx-docs/_build/html
38+
39+
deploy:
40+
needs: build
41+
runs-on: ubuntu-latest
42+
environment:
43+
name: github-pages
44+
url: ${{ steps.deployment.outputs.page_url }}
45+
steps:
46+
- name: Deploy to GitHub Pages
47+
id: deployment
48+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ dist
66
**/generated/timestamp.asm
77
**/generated/version.asm
88
uv.lock
9+
sphinx-docs/_build/

‎sphinx-docs/Makefile‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.PHONY: html pdf livehtml clean
2+
3+
# Mermaid CLI needs a Chrome headless shell; point it at whatever is cached.
4+
CHROME_HS := $(firstword $(wildcard $(HOME)/.cache/puppeteer/chrome-headless-shell/*/chrome-headless-shell-*/chrome-headless-shell))
5+
export PUPPETEER_EXECUTABLE_PATH := $(CHROME_HS)
6+
7+
html:
8+
uv run sphinx-build -b html . _build/html
9+
10+
pdf:
11+
uv run sphinx-build -b latex . _build/latex
12+
cd _build/latex && xelatex f256-superbasic.tex && xelatex f256-superbasic.tex
13+
14+
livehtml:
15+
uv run sphinx-autobuild . _build/html --port 8000
16+
17+
clean:
18+
rm -rf _build

‎sphinx-docs/_static/custom.css‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
/* Wildbits brand colors */
2+
:root {
3+
--wb-navy: #272662;
4+
--wb-red: #EE4025;
5+
--wb-orange: #F1632B;
6+
--wb-gold: #FDBB3A;
7+
--wb-green: #44A348;
8+
--wb-teal: #6BA7BB;
9+
}
10+
11+
/* Consistent table widths */
12+
table.docutils {
13+
width: 100%;
14+
}
15+
16+
/* Mermaid diagram sizing */
17+
.mermaid {
18+
margin: 0.75em 0;
19+
}
20+
21+
.mermaid svg {
22+
max-height: 180px;
23+
}
24+
25+
/* Admonition styling — note */
26+
.admonition.note {
27+
border-left: 4px solid var(--wb-navy);
28+
background: color-mix(in srgb, var(--wb-navy) 8%, transparent);
29+
}
30+
.admonition.note > .admonition-title {
31+
background: color-mix(in srgb, var(--wb-navy) 15%, transparent);
32+
color: var(--wb-navy);
33+
}
34+
35+
/* Admonition styling — warning */
36+
.admonition.warning {
37+
border-left: 4px solid var(--wb-orange);
38+
background: color-mix(in srgb, var(--wb-orange) 8%, transparent);
39+
}
40+
.admonition.warning > .admonition-title {
41+
background: color-mix(in srgb, var(--wb-orange) 15%, transparent);
42+
color: var(--wb-orange);
43+
}
44+
45+
/* Admonition styling — tip / hint */
46+
.admonition.tip, .admonition.hint {
47+
border-left: 4px solid var(--wb-green);
48+
background: color-mix(in srgb, var(--wb-green) 8%, transparent);
49+
}
50+
.admonition.tip > .admonition-title,
51+
.admonition.hint > .admonition-title {
52+
background: color-mix(in srgb, var(--wb-green) 15%, transparent);
53+
color: var(--wb-green);
54+
}
55+
56+
/* Admonition styling — danger / error */
57+
.admonition.danger, .admonition.error {
58+
border-left: 4px solid var(--wb-red);
59+
background: color-mix(in srgb, var(--wb-red) 8%, transparent);
60+
}
61+
.admonition.danger > .admonition-title,
62+
.admonition.error > .admonition-title {
63+
background: color-mix(in srgb, var(--wb-red) 15%, transparent);
64+
color: var(--wb-red);
65+
}
66+
67+
/* Admonition styling — important */
68+
.admonition.important {
69+
border-left: 4px solid var(--wb-gold);
70+
background: color-mix(in srgb, var(--wb-gold) 8%, transparent);
71+
}
72+
.admonition.important > .admonition-title {
73+
background: color-mix(in srgb, var(--wb-gold) 15%, transparent);
74+
color: #8a6d00;
75+
}
76+
77+
/* Generic admonitions (custom title) */
78+
.admonition:not(.note):not(.warning):not(.tip):not(.hint):not(.danger):not(.error):not(.important) {
79+
border-left: 4px solid var(--wb-teal);
80+
background: color-mix(in srgb, var(--wb-teal) 8%, transparent);
81+
}
82+
.admonition:not(.note):not(.warning):not(.tip):not(.hint):not(.danger):not(.error):not(.important) > .admonition-title {
83+
background: color-mix(in srgb, var(--wb-teal) 15%, transparent);
84+
color: var(--wb-navy);
85+
}
86+
87+
/* Dark mode overrides */
88+
body[data-theme="dark"] .admonition.note {
89+
background: color-mix(in srgb, var(--wb-navy) 15%, transparent);
90+
}
91+
body[data-theme="dark"] .admonition.note > .admonition-title {
92+
background: color-mix(in srgb, var(--wb-navy) 25%, transparent);
93+
color: var(--wb-teal);
94+
}
95+
body[data-theme="dark"] .admonition.warning {
96+
background: color-mix(in srgb, var(--wb-orange) 12%, transparent);
97+
}
98+
body[data-theme="dark"] .admonition.warning > .admonition-title {
99+
background: color-mix(in srgb, var(--wb-orange) 20%, transparent);
100+
color: var(--wb-orange);
101+
}
102+
body[data-theme="dark"] .admonition.tip,
103+
body[data-theme="dark"] .admonition.hint {
104+
background: color-mix(in srgb, var(--wb-green) 12%, transparent);
105+
}
106+
body[data-theme="dark"] .admonition.tip > .admonition-title,
107+
body[data-theme="dark"] .admonition.hint > .admonition-title {
108+
background: color-mix(in srgb, var(--wb-green) 20%, transparent);
109+
color: var(--wb-green);
110+
}
111+
body[data-theme="dark"] .admonition.danger,
112+
body[data-theme="dark"] .admonition.error {
113+
background: color-mix(in srgb, var(--wb-red) 12%, transparent);
114+
}
115+
body[data-theme="dark"] .admonition.danger > .admonition-title,
116+
body[data-theme="dark"] .admonition.error > .admonition-title {
117+
background: color-mix(in srgb, var(--wb-red) 20%, transparent);
118+
color: var(--wb-red);
119+
}
120+
body[data-theme="dark"] .admonition.important {
121+
background: color-mix(in srgb, var(--wb-gold) 12%, transparent);
122+
}
123+
body[data-theme="dark"] .admonition.important > .admonition-title {
124+
background: color-mix(in srgb, var(--wb-gold) 20%, transparent);
125+
color: var(--wb-gold);
126+
}
127+
body[data-theme="dark"] .admonition:not(.note):not(.warning):not(.tip):not(.hint):not(.danger):not(.error):not(.important) {
128+
background: color-mix(in srgb, var(--wb-teal) 12%, transparent);
129+
}
130+
body[data-theme="dark"] .admonition:not(.note):not(.warning):not(.tip):not(.hint):not(.danger):not(.error):not(.important) > .admonition-title {
131+
background: color-mix(in srgb, var(--wb-teal) 20%, transparent);
132+
color: var(--wb-teal);
133+
}

‎sphinx-docs/conf.py‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
3+
import sys
4+
import os
5+
sys.path.insert(0, os.path.abspath("."))
6+
7+
from superbasic_lexer import SuperBASICLexer
8+
from sphinx.highlighting import lexers
9+
10+
_lexer = SuperBASICLexer()
11+
lexers["basic"] = _lexer
12+
lexers["superbasic"] = _lexer
13+
14+
project = "Wildbits SuperBASIC"
15+
copyright = "2023-2026, Paul Robson & Wildbits Computing Company"
16+
author = "Paul Robson & Wildbits Computing Company"
17+
release = "1.1"
18+
19+
extensions = [
20+
"myst_parser",
21+
"sphinxcontrib.mermaid",
22+
"sphinx_copybutton",
23+
"sphinx_design",
24+
]
25+
26+
myst_enable_extensions = [
27+
"colon_fence",
28+
"deflist",
29+
"fieldlist",
30+
"tasklist",
31+
]
32+
33+
templates_path = ["_templates"]
34+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
35+
36+
# -- Options for HTML output -------------------------------------------------
37+
38+
html_theme = "furo"
39+
html_static_path = ["_static"]
40+
html_css_files = ["custom.css"]
41+
html_title = "Wildbits SuperBASIC"
42+
43+
html_theme_options = {
44+
"navigation_with_keys": True,
45+
}
46+
47+
# -- Options for LaTeX output ------------------------------------------------
48+
49+
latex_documents = [
50+
(
51+
"index",
52+
"f256-superbasic.tex",
53+
"Wildbits SuperBASIC Reference Manual",
54+
"Paul Robson",
55+
"manual",
56+
),
57+
]
58+
59+
latex_elements = {
60+
"papersize": "letterpaper",
61+
"pointsize": "11pt",
62+
"fncychap": r"\usepackage[Bjornstrup]{fncychap}",
63+
"fontpkg": r"""
64+
\usepackage{fontspec}
65+
\setmainfont{NotoSerif}[
66+
Extension=.ttf,
67+
UprightFont=*-Regular,
68+
BoldFont=*-Bold,
69+
ItalicFont=*-Italic,
70+
BoldItalicFont=*-BoldItalic,
71+
]
72+
\setsansfont{NotoSans}[
73+
Extension=.ttf,
74+
UprightFont=*-Regular,
75+
BoldFont=*-Bold,
76+
ItalicFont=*-Italic,
77+
BoldItalicFont=*-BoldItalic,
78+
]
79+
\setmonofont{NotoSansMono}[
80+
Extension=.ttf,
81+
UprightFont=*-Regular,
82+
BoldFont=*-Bold,
83+
]
84+
""",
85+
"geometry": r"\usepackage[letterpaper,inner=1.5in,outer=1.0in,top=0.75in,bottom=0.75in]{geometry}",
86+
"preamble": r"""
87+
% Match original reference manual styling
88+
\definecolor{darkblue}{rgb}{0.1, 0.0, 0.6}
89+
\definecolor{silver}{rgb}{0.85, 0.85, 0.85}
90+
\ChNumVar{\color{darkblue}\fontsize{76}{80}\usefont{OT1}{pzc}{m}{n}\selectfont}
91+
\ChTitleVar{\color{darkblue}\raggedleft\Huge\sffamily\bfseries}
92+
93+
% Dark blue section headings
94+
\usepackage{sectsty}
95+
\allsectionsfont{\color{darkblue}\bfseries\sffamily}
96+
97+
% Tighter TOC spacing
98+
\usepackage{tocloft}
99+
\setlength{\cftbeforechapskip}{6pt}
100+
\setlength{\cftbeforesecskip}{2pt}
101+
\renewcommand{\cftchapleader}{\cftdotfill{\cftdotsep}}
102+
103+
% Reduce float spacing
104+
\setlength{\floatsep}{8pt plus 2pt minus 2pt}
105+
\setlength{\textfloatsep}{10pt plus 2pt minus 2pt}
106+
\setlength{\intextsep}{8pt plus 2pt minus 2pt}
107+
108+
% Black hyperlinks like the original
109+
\hypersetup{colorlinks=true,linkcolor=black,urlcolor=darkblue}
110+
111+
% Plain code blocks — no frame, no background (like the original verbatim style)
112+
\sphinxsetup{
113+
VerbatimColor={rgb}{1,1,1},
114+
VerbatimBorderColor={rgb}{1,1,1},
115+
verbatimborder=0pt,
116+
}
117+
\fvset{fontsize=\small}
118+
""",
119+
"maketitle": r"""
120+
\begin{titlepage}
121+
\colorbox{silver}{\makebox[\textwidth][r]{
122+
\shortstack{
123+
\vspace{3cm} \\
124+
\color{darkblue}\bfseries\sffamily\Huge Wildbits SuperBASIC Reference Manual}} \\
125+
}
126+
\vfill
127+
\hfill\mbox{\color{darkblue}\bfseries\sffamily\Large Paul Robson}
128+
\hfill\mbox{\color{darkblue}\bfseries\sffamily\large \today}
129+
\end{titlepage}
130+
""",
131+
"tableofcontents": r"\sphinxtableofcontents",
132+
}
133+
134+
# -- Mermaid options ---------------------------------------------------------
135+
136+
mermaid_init_js = """mermaid.initialize({
137+
startOnLoad: true,
138+
theme: 'base',
139+
themeVariables: {
140+
primaryColor: '#272662',
141+
primaryTextColor: '#fff',
142+
primaryBorderColor: '#1a1a4a',
143+
secondaryColor: '#F1632B',
144+
secondaryTextColor: '#fff',
145+
secondaryBorderColor: '#d14a1a',
146+
tertiaryColor: '#44A348',
147+
tertiaryTextColor: '#fff',
148+
tertiaryBorderColor: '#358a38',
149+
lineColor: '#272662',
150+
textColor: '#272662',
151+
nodeBorder: '#272662',
152+
},
153+
themeCSS: '.node .label { color: #fff !important; } .edgeLabel { color: #272662 !important; }'
154+
});"""
155+
mermaid_pdfcrop = "pdfcrop"

0 commit comments

Comments
 (0)