warehack.ing/openocd-python-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge feat/scaffold: Starlight site with config, CSS, logo, stubs

Browse Source
This commit is contained in:
Ryan Malloy 2026-02-14 18:23:55 -07:00
commit e6829d0a53
35 changed files with 8334 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
astro.config.mjs Normal file
View File

@ -0,0 +1,86 @@
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://openocd-python.warehack.ing',
telemetry: false,
devToolbar: { enabled: false },
integrations: [
starlight({
title: 'openocd-python',
description: 'Typed async-first Python bindings for OpenOCD',
logo: {
src: './src/assets/logo.svg',
alt: 'openocd-python',
},
favicon: '/favicon.svg',
social: [
{
icon: 'github',
label: 'GitHub',
href: 'https://git.supported.systems/warehack.ing/openocd-python',
},
],
customCss: ['./src/styles/custom.css'],
sidebar: [
{
label: 'Getting Started',
items: [
{ label: 'Installation', slug: 'getting-started/installation' },
{ label: 'First Connection', slug: 'getting-started/first-connection' },
{ label: 'CLI Reference', slug: 'getting-started/cli' },
{ label: 'Quick Start', slug: 'getting-started/quick-start' },
],
},
{
label: 'Guides',
items: [
{ label: 'Session Lifecycle', slug: 'guides/session-lifecycle' },
{ label: 'Async vs Sync', slug: 'guides/async-vs-sync' },
{ label: 'Error Handling', slug: 'guides/error-handling' },
{ label: 'Target Control', slug: 'guides/target-control' },
{ label: 'Memory Operations', slug: 'guides/memory-operations' },
{ label: 'Register Access', slug: 'guides/register-access' },
{ label: 'Flash Programming', slug: 'guides/flash-programming' },
{ label: 'Breakpoints & Watchpoints', slug: 'guides/breakpoints' },
{ label: 'JTAG Operations', slug: 'guides/jtag-operations' },
{ label: 'SVD Register Decoding', slug: 'guides/svd-decoding' },
{ label: 'RTT Communication', slug: 'guides/rtt-communication' },
{ label: 'Transport & Adapter', slug: 'guides/transport-adapter' },
{ label: 'Event Callbacks', slug: 'guides/event-callbacks' },
],
},
{
label: 'API Reference',
items: [
{ label: 'Session API', slug: 'reference/session-api' },
{ label: 'Types', slug: 'reference/types' },
{ label: 'Exceptions', slug: 'reference/exceptions' },
{ label: 'Connection Layer', slug: 'reference/connection-layer' },
{ label: 'Method Index', slug: 'reference/method-index' },
],
},
{
label: 'Examples',
items: [
{ label: 'Debug Session', slug: 'examples/debug-session' },
{ label: 'Flash Programming', slug: 'examples/flash-programming' },
{ label: 'SVD Inspection', slug: 'examples/svd-inspection' },
],
},
],
}),
],
vite: {
server: {
host: '0.0.0.0',
...(process.env.VITE_HMR_HOST && {
hmr: {
host: process.env.VITE_HMR_HOST,
protocol: 'wss',
clientPort: 443,
},
}),
},
},
});

7902
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

19
package.json Normal file
View File

@ -0,0 +1,19 @@
{
"name": "openocd-python-docs",
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"astro": "^5.17.2",
"@astrojs/starlight": "^0.35.0",
"sharp": "^0.33.0",
"astro-icon": "^1.1.0",
"@iconify-json/lucide": "^1.2.0"
}
}

25
public/favicon.svg Normal file
View File

@ -0,0 +1,25 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
<!-- Chip body -->
<rect x="12" y="12" width="24" height="24" rx="3" stroke="#0d9488" stroke-width="2.5" fill="none"/>
<!-- Inner die -->
<rect x="18" y="18" width="12" height="12" rx="1.5" fill="#0d9488" opacity="0.15"/>
<rect x="18" y="18" width="12" height="12" rx="1.5" stroke="#0d9488" stroke-width="1.5" fill="none"/>
<!-- Pin 1 marker -->
<circle cx="21" cy="21" r="1.5" fill="#0d9488" opacity="0.6"/>
<!-- Top pins -->
<line x1="18" y1="12" x2="18" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="24" y1="12" x2="24" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="30" y1="12" x2="30" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Bottom pins -->
<line x1="18" y1="36" x2="18" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="24" y1="36" x2="24" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="30" y1="36" x2="30" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Left pins -->
<line x1="12" y1="18" x2="5" y2="18" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="12" y1="24" x2="5" y2="24" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="12" y1="30" x2="5" y2="30" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Right pins -->
<line x1="36" y1="18" x2="43" y2="18" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="36" y1="24" x2="43" y2="24" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="36" y1="30" x2="43" y2="30" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

25
src/assets/logo.svg Normal file
View File

@ -0,0 +1,25 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
<!-- Chip body -->
<rect x="12" y="12" width="24" height="24" rx="3" stroke="#0d9488" stroke-width="2.5" fill="none"/>
<!-- Inner die -->
<rect x="18" y="18" width="12" height="12" rx="1.5" fill="#0d9488" opacity="0.15"/>
<rect x="18" y="18" width="12" height="12" rx="1.5" stroke="#0d9488" stroke-width="1.5" fill="none"/>
<!-- Pin 1 marker -->
<circle cx="21" cy="21" r="1.5" fill="#0d9488" opacity="0.6"/>
<!-- Top pins -->
<line x1="18" y1="12" x2="18" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="24" y1="12" x2="24" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="30" y1="12" x2="30" y2="5" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Bottom pins -->
<line x1="18" y1="36" x2="18" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="24" y1="36" x2="24" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="30" y1="36" x2="30" y2="43" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Left pins -->
<line x1="12" y1="18" x2="5" y2="18" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="12" y1="24" x2="5" y2="24" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="12" y1="30" x2="5" y2="30" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<!-- Right pins -->
<line x1="36" y1="18" x2="43" y2="18" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="36" y1="24" x2="43" y2="24" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
<line x1="36" y1="30" x2="43" y2="30" stroke="#0d9488" stroke-width="2" stroke-linecap="round"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

7
src/content.config.ts Normal file
View File

@ -0,0 +1,7 @@
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

6
src/content/docs/examples/debug-session.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Debug Session
description: Complete example of a debug session with target control
---
Content coming soon.

6
src/content/docs/examples/flash-programming.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Flash Programming
description: End-to-end flash erase, write, and verify example
---
Content coming soon.

6
src/content/docs/examples/svd-inspection.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: SVD Inspection
description: Load an SVD file and decode peripheral registers live
---
Content coming soon.

6
src/content/docs/getting-started/cli.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: CLI Reference
description: Command-line interface for openocd-python
---
Content coming soon.

6
src/content/docs/getting-started/first-connection.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: First Connection
description: Connect to an OpenOCD instance for the first time
---
Content coming soon.

6
src/content/docs/getting-started/installation.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Installation
description: Install openocd-python and its dependencies
---
Content coming soon.

6
src/content/docs/getting-started/quick-start.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Quick Start
description: Get up and running with openocd-python in minutes
---
Content coming soon.

6
src/content/docs/guides/async-vs-sync.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Async vs Sync
description: Choosing between async and synchronous APIs
---
Content coming soon.

6
src/content/docs/guides/breakpoints.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Breakpoints & Watchpoints
description: Set and manage hardware and software breakpoints
---
Content coming soon.

6
src/content/docs/guides/error-handling.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Error Handling
description: Exception hierarchy and error recovery patterns
---
Content coming soon.

6
src/content/docs/guides/event-callbacks.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Event Callbacks
description: Subscribe to target events and state changes
---
Content coming soon.

6
src/content/docs/guides/flash-programming.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Flash Programming
description: Erase, write, and verify flash memory
---
Content coming soon.

6
src/content/docs/guides/jtag-operations.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: JTAG Operations
description: Low-level JTAG scan chain access and TAP control
---
Content coming soon.

6
src/content/docs/guides/memory-operations.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Memory Operations
description: Read and write target memory at various widths
---
Content coming soon.

6
src/content/docs/guides/register-access.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Register Access
description: Read and write CPU registers by name or number
---
Content coming soon.

6
src/content/docs/guides/rtt-communication.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: RTT Communication
description: Real-Time Transfer channel setup and data streaming
---
Content coming soon.

6
src/content/docs/guides/session-lifecycle.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Session Lifecycle
description: Understanding session creation, connection, and teardown
---
Content coming soon.

6
src/content/docs/guides/svd-decoding.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: SVD Register Decoding
description: Decode peripheral registers using CMSIS-SVD metadata
---
Content coming soon.

6
src/content/docs/guides/target-control.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Target Control
description: Halt, resume, reset, and step through targets
---
Content coming soon.

6
src/content/docs/guides/transport-adapter.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Transport & Adapter
description: Query and configure debug transport and adapter settings
---
Content coming soon.

32
src/content/docs/index.mdx Normal file
View File

@ -0,0 +1,32 @@
---
title: openocd-python
description: Typed async-first Python bindings for OpenOCD
template: splash
hero:
tagline: Typed async-first Python bindings for OpenOCD — control targets, read memory, program flash, and decode SVD registers from Python.
actions:
- text: Get Started
link: /getting-started/installation/
icon: right-arrow
- text: View on GitHub
link: https://git.supported.systems/warehack.ing/openocd-python
icon: external
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
<CardGrid stagger>
<Card title="Async-First Design" icon="rocket">
Full async/await API with sync wrappers. Use `Session.connect()` for async or `Session.connect_sync()` for synchronous code.
</Card>
<Card title="9 Subsystems" icon="puzzle">
Target control, memory, registers, flash, breakpoints, JTAG, SVD, RTT, and transport — all from one session.
</Card>
<Card title="Type-Safe" icon="approve-check">
Frozen dataclasses for all return types. Explicit exception hierarchy. Full type annotations throughout.
</Card>
<Card title="Safety-Critical Ready" icon="setting">
Defensive parsing, explicit error handling, and thorough test coverage. Used in avionics, medical, and automotive contexts.
</Card>
</CardGrid>

6
src/content/docs/reference/connection-layer.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Connection Layer
description: TclRpcConnection and TelnetConnection internals
---
Content coming soon.

6
src/content/docs/reference/exceptions.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Exceptions
description: Exception hierarchy rooted at OpenOCDError
---
Content coming soon.

6
src/content/docs/reference/method-index.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Method Index
description: Alphabetical index of all public methods
---
Content coming soon.

6
src/content/docs/reference/session-api.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Session API
description: Complete Session and SyncSession class reference
---
Content coming soon.

6
src/content/docs/reference/types.mdx Normal file
View File

@ -0,0 +1,6 @@
---
title: Types
description: Frozen dataclass types returned by the API
---
Content coming soon.

1
src/env.d.ts vendored Normal file
View File

@ -0,0 +1 @@
/// <reference path="../.astro/types.d.ts" />

82
src/styles/custom.css Normal file
View File

@ -0,0 +1,82 @@
/* Custom theme for openocd-python docs */
/* Hardware engineering palette: teal, slate, amber */
:root {
/* Accent colors - teal */
--sl-color-accent-low: #0d3b3f;
--sl-color-accent: #0d9488;
--sl-color-accent-high: #5eead4;
/* Text colors */
--sl-color-white: #f8fafc;
--sl-color-gray-1: #e2e8f0;
--sl-color-gray-2: #cbd5e1;
--sl-color-gray-3: #94a3b8;
--sl-color-gray-4: #64748b;
--sl-color-gray-5: #334155;
--sl-color-gray-6: #1e293b;
--sl-color-black: #0f172a;
/* Banner/badge accent - amber for warnings/highlights */
--sl-color-orange-low: #451a03;
--sl-color-orange: #f59e0b;
--sl-color-orange-high: #fde68a;
}
/* Light theme overrides */
:root[data-theme='light'] {
--sl-color-accent-low: #ccfbf1;
--sl-color-accent: #0d9488;
--sl-color-accent-high: #134e4a;
--sl-color-white: #0f172a;
--sl-color-gray-1: #1e293b;
--sl-color-gray-2: #334155;
--sl-color-gray-3: #64748b;
--sl-color-gray-4: #94a3b8;
--sl-color-gray-5: #e2e8f0;
--sl-color-gray-6: #f1f5f9;
--sl-color-black: #f8fafc;
}
/* Code blocks - darker slate with teal accents */
:root {
--sl-color-bg-code: #0c1222;
}
/* Sidebar - subtle depth */
.sidebar-pane {
border-right: 1px solid var(--sl-color-gray-5);
}
/* Links - teal hover with smooth transition */
a:hover {
color: var(--sl-color-accent-high);
transition: color 0.15s ease;
}
/* Subtle PCB-trace pattern on hero area */
.hero {
background-image:
linear-gradient(90deg, rgba(13, 148, 136, 0.03) 1px, transparent 1px),
linear-gradient(rgba(13, 148, 136, 0.03) 1px, transparent 1px);
background-size: 24px 24px;
}
/* Table styling */
table {
border-collapse: collapse;
}
th {
background: var(--sl-color-gray-6);
font-weight: 600;
}
/* Inline code */
:not(pre) > code {
background: var(--sl-color-gray-6);
padding: 0.15em 0.35em;
border-radius: 4px;
font-size: 0.9em;
}

5
tsconfig.json Normal file
View File

@ -0,0 +1,5 @@
{
"extends": "astro/tsconfigs/strict",
"include": ["src/**/*"],
"exclude": ["node_modules"]
}