{"id":46940921,"url":"https://github.com/pathsim/docs","last_synced_at":"2026-03-11T07:03:29.615Z","repository":{"id":333892390,"uuid":"1139154525","full_name":"pathsim/docs","owner":"pathsim","description":"The Repo for the PathSim Docs.","archived":false,"fork":false,"pushed_at":"2026-03-10T19:47:22.000Z","size":29104,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-11T01:21:28.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.pathsim.org/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pathsim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-21T15:40:35.000Z","updated_at":"2026-03-10T19:47:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pathsim/docs","commit_stats":null,"previous_names":["pathsim/pathsim-docs","pathsim/docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pathsim/docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathsim%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathsim%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathsim%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathsim%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pathsim","download_url":"https://codeload.github.com/pathsim/docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathsim%2Fdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30373521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-11T07:03:29.177Z","updated_at":"2026-03-11T07:03:29.607Z","avatar_url":"https://github.com/pathsim.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/pathsim/pathsim-docs/master/static/pathsim_logo.png\" width=\"300\" alt=\"PathSim Logo\" /\u003e\n\u003c/p\u003e\n\n------------\n\n# PathSim Docs - Unified Documentation Site\n\nA unified documentation site for the PathSim ecosystem, featuring API references, interactive examples, and versioned documentation for PathSim, PathSim-Chem, and PathSim-Vehicle. Built with SvelteKit and hosted at [docs.pathsim.org](https://docs.pathsim.org).\n\n## Tech Stack\n\n- [SvelteKit 2](https://kit.svelte.dev/) with Svelte 5 runes\n- [Griffe](https://mkdocstrings.github.io/griffe/) for Python API extraction\n- [Pyodide](https://pyodide.org/) for interactive notebook execution\n- [CodeMirror 6](https://codemirror.net/) for code highlighting\n- [KaTeX](https://katex.org/) for math rendering\n- [Marked](https://marked.js.org/) for Markdown processing\n- [Transformers.js](https://huggingface.co/docs/transformers.js/) for semantic search (e5-small-v2)\n\n## Getting Started\n\n```bash\nnpm install\nnpm run dev\n```\n\nFor production:\n\n```bash\npython scripts/build.py --all  # Extract API docs, notebooks, and build indexes\nnpm run build\nnpm run preview\n```\n\n## Project Structure\n\n```\nsrc/\n├── lib/\n│   ├── api/               # API data system\n│   │   ├── versions.ts    # Version loading utilities, manifest types\n│   │   └── generated/     # TypeScript types (index.ts)\n│   ├── components/\n│   │   ├── api/           # API documentation components\n│   │   │   ├── ModuleDoc.svelte\n│   │   │   ├── ClassDoc.svelte\n│   │   │   ├── FunctionDoc.svelte\n│   │   │   ├── DocstringRenderer.svelte\n│   │   │   ├── TypeRef.svelte\n│   │   │   └── ApiToc.svelte\n│   │   ├── common/        # Shared UI components\n│   │   │   ├── Icon.svelte\n│   │   │   ├── Tooltip.svelte\n│   │   │   ├── CodeBlock.svelte\n│   │   │   ├── NotebookCell.svelte\n│   │   │   ├── MarkdownRenderer.svelte\n│   │   │   └── RstRenderer.svelte\n│   │   ├── layout/        # Page layout\n│   │   │   ├── Header.svelte\n│   │   │   ├── Sidebar.svelte      # Includes version selector\n│   │   │   ├── MobileDrawer.svelte\n│   │   │   └── DocLayout.svelte\n│   │   ├── notebook/      # Jupyter notebook rendering\n│   │   │   ├── Notebook.svelte\n│   │   │   ├── CodeCell.svelte\n│   │   │   ├── MarkdownCell.svelte\n│   │   │   └── CellOutput.svelte\n│   │   ├── examples/      # Examples page components\n│   │   │   └── ExamplesToc.svelte\n│   │   ├── search/        # Search UI components\n│   │   │   ├── SearchInput.svelte\n│   │   │   └── SearchResult.svelte\n│   │   └── pages/         # Full page components\n│   │       ├── PackageOverview.svelte\n│   │       └── PackageApi.svelte\n│   ├── config/            # Centralized configuration\n│   │   ├── packages.ts    # Package metadata, links, features, installation\n│   │   ├── pyodide.ts     # Python runtime config\n│   │   └── links.ts       # External URLs\n│   ├── notebook/          # Notebook parsing and loading\n│   │   ├── types.ts\n│   │   ├── parser.ts\n│   │   └── loader.ts      # Version manifest and notebook loading\n│   ├── pyodide/           # Python execution (Web Worker)\n│   │   ├── index.ts       # Main thread bridge\n│   │   ├── worker.ts      # Web Worker implementation\n│   │   └── types.ts       # Message protocol types\n│   ├── semantic/          # Semantic search (client-side)\n│   │   ├── model.ts       # Embedding model loader (e5-small-v2)\n│   │   ├── similarity.ts  # Cosine similarity search\n│   │   └── index.ts       # Public API\n│   ├── stores/            # Svelte stores\n│   │   ├── apiContext.ts\n│   │   ├── examplesContext.ts\n│   │   ├── notebookStore.ts\n│   │   ├── pyodideStore.ts\n│   │   ├── versionStore.ts        # Per-package version persistence\n│   │   ├── packageVersionsStore.ts # Pyodide package versions\n│   │   ├── searchNavigation.ts\n│   │   └── themeStore.ts\n│   └── utils/\n│       ├── search.ts      # Search with dynamic index loading\n│       ├── crossref.ts    # Cross-reference linking\n│       ├── codemirror.ts  # Editor setup\n│       └── clipboard.ts\n├── routes/\n│   ├── +page.svelte       # Home (search, package cards)\n│   ├── +layout.svelte     # Root layout\n│   ├── pathsim/           # Static package routes (overview only)\n│   │   └── +page.svelte\n│   ├── chem/\n│   │   └── +page.svelte\n│   ├── vehicle/\n│   │   └── +page.svelte\n│   └── [package]/         # Dynamic versioned routes\n│       ├── +layout.ts     # Package layout loader\n│       ├── [version]/\n│       │   ├── +layout.ts     # Version validation, manifest loading\n│       │   ├── +layout.svelte # Version context provider\n│       │   ├── api/\n│       │   │   ├── +page.ts   # Load versioned API data\n│       │   │   └── +page.svelte\n│       │   └── examples/\n│       │       ├── +page.ts   # Load versioned notebook list\n│       │       ├── +page.svelte\n│       │       └── [slug]/\n│       │           ├── +page.ts   # Load versioned notebook\n│       │           └── +page.svelte\n└── app.css                # Global design system\n\nscripts/\n├── build.py               # Main build script (API, notebooks, indexes)\n├── build-indexes.py       # Standalone index generation\n├── build-embeddings.py    # Generate semantic search embeddings\n├── rebuild-manifests.py   # Rebuild notebook manifests (metadata only)\n├── requirements.txt\n└── lib/\n    ├── config.py          # Build configuration (min versions, paths)\n    ├── api.py             # API extraction using Griffe\n    ├── notebooks.py       # Notebook processing (incl. thumbnail extraction)\n    ├── git.py             # Git operations (tags, checkout)\n    └── executor.py        # Parallel execution utilities\n\nstatic/\n├── {package}/             # Per-package versioned content\n│   ├── manifest.json      # Package manifest (versions, latest)\n│   └── {tag}/             # Per-version content (e.g., v0.16.4)\n│       ├── api.json           # API documentation\n│       ├── manifest.json      # Notebook metadata (incl. thumbnails)\n│       ├── search-index.json  # Versioned keyword search index\n│       ├── crossref-index.json # Versioned crossref index\n│       ├── embeddings-index.json # Versioned semantic search embeddings\n│       ├── notebooks/         # Jupyter notebook files\n│       ├── outputs/           # Pre-computed cell outputs\n│       └── figures/           # Pre-rendered figures\n└── *.png                  # Logo files\n```\n\n---\n\n## Architecture Overview\n\n### Data Flow\n\n```\n┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐\n│ Python Packages │────\u003e│ scripts/build.py│────\u003e│ Per-Version     │\n│ (pathsim, etc.) │     │ (Griffe)        │     │ Static Files    │\n└─────────────────┘     └─────────────────┘     └─────────────────┘\n                                                        │\n                        For each git tag:               v\n                        ┌─────────────────────────────────────────┐\n                        │ static/{package}/{tag}/                 │\n                        │   ├── api.json                          │\n                        │   ├── manifest.json (notebooks)         │\n                        │   ├── search-index.json                 │\n                        │   ├── crossref-index.json               │\n                        │   ├── notebooks/                        │\n                        │   └── figures/                          │\n                        └─────────────────────────────────────────┘\n```\n\n### URL Scheme\n\n| URL | Page |\n|-----|------|\n| `/` | Home with search and package cards |\n| `/pathsim` | PathSim overview (features, installation) |\n| `/pathsim/v0.16.4/api` | API reference (specific version) |\n| `/pathsim/v0.16.4/examples` | Example notebooks gallery |\n| `/pathsim/v0.16.4/examples/harmonic-oscillator` | Specific notebook |\n| `/chem`, `/vehicle` | Other packages (same structure) |\n\n### Key Abstractions\n\n| Layer | Purpose | Key Files |\n|-------|---------|-----------|\n| **Build Script** | Extract API, notebooks, indexes | `scripts/build.py` |\n| **Keyword Search** | Per-version search indexes | `search.ts`, `search-index.json` |\n| **Semantic Search** | Natural language search via embeddings | `semantic/`, `embeddings-index.json` |\n| **Cross-refs** | Per-version link resolution | `crossref.ts`, `TypeRef.svelte` |\n| **Version Store** | Persist selected version per package | `versionStore.ts` |\n| **Notebook Loader** | Fetch versioned notebooks | `loader.ts` |\n| **Pyodide Worker** | Execute Python with versioned packages | `pyodide/worker.ts` |\n\n---\n\n## Build System\n\nThe main build script handles all content generation:\n\n```bash\n# Build specific package (smart mode - only missing versions)\npython scripts/build.py --package pathsim\n\n# Rebuild all versions for all packages\npython scripts/build.py --all\n\n# Build indexes only (for existing content)\npython scripts/build-indexes.py\n```\n\n### What It Does\n\n1. **API Extraction**: Uses Griffe to extract from Python source\n2. **Notebook Processing**: Copies notebooks, extracts metadata\n3. **Index Generation**: Creates search and crossref indexes per version\n4. **Manifest Generation**: Creates package manifest with version list\n\n### Configuration (`scripts/lib/config.py`)\n\n```python\nMIN_SUPPORTED_VERSIONS = {\n    \"pathsim\": \"0.7\",\n    \"pathsim-chem\": \"0.1\",\n    \"pathsim-vehicle\": \"0.1\"\n}\n```\n\n---\n\n## Search System\n\nSearch uses per-version indexes loaded dynamically.\n\n### Index Structure\n\nEach version has its own `search-index.json`:\n\n```json\n[\n  {\n    \"name\": \"Integrator\",\n    \"type\": \"class\",\n    \"moduleName\": \"pathsim.blocks.integrator\",\n    \"path\": \"pathsim/v0.16.4/api#Integrator\",\n    \"description\": \"Integration block for ODE systems\"\n  }\n]\n```\n\n### Search Features\n\n- **Multi-term queries**: Each term scored independently\n- **Scoring hierarchy**: Exact match (100) \u003e prefix (50) \u003e contains (30) \u003e description (10)\n- **Type boosting**: Pages 1.5x, classes 1.2x, examples 1.15x\n- **Keyboard shortcut**: Ctrl+F focuses search bar\n\n---\n\n## Semantic Search\n\nIn addition to keyword search, the documentation supports semantic search powered by Transformers.js running client-side.\n\n### How It Works\n\n1. **Build time**: `build-embeddings.py` generates embeddings for all API items and examples using e5-small-v2\n2. **Load time**: Embeddings index loaded per-version from `embeddings-index.json`\n3. **Query time**: User query embedded in browser, cosine similarity finds relevant results\n\n### Embedding Index Structure\n\n```json\n{\n  \"items\": [\n    {\n      \"name\": \"Integrator\",\n      \"type\": \"class\",\n      \"path\": \"pathsim/v0.16.4/api#Integrator\",\n      \"embedding\": [0.012, -0.034, ...]\n    }\n  ]\n}\n```\n\n### Features\n\n- **Natural language queries**: \"How do I integrate a signal?\" finds `Integrator` class\n- **Client-side inference**: No server required, runs in browser via ONNX Runtime\n- **Lazy loading**: Model loaded only when semantic search is triggered\n- **Combined results**: Semantic results merged with keyword search for best coverage\n\n---\n\n## Cross-Reference System\n\nAutomatically links class/function names in docstrings to their API documentation.\n\n### Supported Patterns\n\n```rst\n:class:`Integrator`       # RST role syntax\n`Integrator`              # Backtick code\n'Integrator'              # Single-quoted names\n```\n\n### Per-Version Resolution\n\nCross-references resolve to the current version's API:\n\n```\nIntegrator → /pathsim/v0.16.4/api#Integrator\n```\n\n---\n\n## Versioned Documentation\n\nEach package maintains historical API versions with full content.\n\n### Package Manifest\n\nLocated at `static/{package}/manifest.json`:\n\n```json\n{\n  \"package\": \"pathsim\",\n  \"latestTag\": \"v0.16.4\",\n  \"versions\": [\n    {\n      \"tag\": \"v0.16.4\",\n      \"released\": \"2025-01-17\",\n      \"hasExamples\": true\n    },\n    {\n      \"tag\": \"v0.9.0\",\n      \"released\": \"2025-09-26\",\n      \"hasExamples\": false\n    }\n  ]\n}\n```\n\n### Version Selection\n\n- **Sidebar dropdown**: Shows all versions with \"latest\" badge\n- **Persistence**: Selected version stored in localStorage per package\n- **Smart navigation**: When switching to a version without examples, redirects to overview\n\n---\n\n## Interactive Notebooks\n\nJupyter notebooks run in the browser via Pyodide with versioned package support.\n\n### Execution\n\n- Pyodide runs in a Web Worker (non-blocking)\n- **Versioned packages**: Installs specific version matching the docs (e.g., `pathsim==0.16.4`)\n- Cell outputs rendered: text, images, HTML, errors\n- Math support via KaTeX\n\n### Keyboard Shortcuts\n\nJupyter-style keyboard shortcuts for code cells:\n\n| Shortcut | Action |\n|----------|--------|\n| `Ctrl+Enter` | Run cell and advance to next |\n| `Ctrl+Shift+Enter` | Run cell (stay in place) |\n| `Escape` | Unfocus current cell |\n\n- Pressing `Ctrl+Enter` with no cell focused auto-selects the first code cell\n- Focused cells show a highlight border for visibility\n- Cells scroll into view when focused\n\n### Example Thumbnails\n\nExample tiles on the gallery page display thumbnails extracted from notebook figures:\n\n- Extracted from the first `.. image::` (RST) or `![](...)` (Markdown) directive\n- Falls back to description text if no figure found\n- Thumbnails stored in version manifest metadata\n\n### Version-Aware Execution\n\nWhen viewing `/pathsim/v0.14.0/examples/...`, Pyodide installs `pathsim==0.14.0` to ensure examples work correctly with that version's API.\n\n---\n\n## Configuration\n\n### Package Configuration (`src/lib/config/packages.ts`)\n\nCentral source of truth for all package metadata:\n\n```typescript\nexport const packages = {\n  pathsim: {\n    id: 'pathsim',\n    name: 'PathSim',\n    description: 'Block-diagram simulation framework',\n    logo: 'pathsim_logo.png',\n    docs: 'pathsim',\n    api: 'pathsim/api',\n    examples: 'pathsim/examples',\n    pypi: 'https://pypi.org/project/pathsim',\n    conda: 'https://anaconda.org/conda-forge/pathsim',\n    github: 'https://github.com/pathsim/pathsim',\n    features: [...],\n    installation: [\n      { name: 'pip', command: 'pip install pathsim' },\n      { name: 'conda', command: 'conda install -c conda-forge pathsim', minVersion: '0.14.0' }\n    ],\n    quickstart: { ... }\n  }\n};\n```\n\n### Pyodide Configuration (`src/lib/config/pyodide.ts`)\n\n```typescript\nexport const PYODIDE_VERSION = '0.26.2';\nexport const PYTHON_PACKAGES = [\n  { pip: 'pathsim', required: true, pre: true, import: 'pathsim' },\n  { pip: 'matplotlib', required: true, pre: false, import: 'matplotlib' }\n];\nexport const TIMEOUTS = { INIT: 120000, EXECUTION: 60000 };\n```\n\n---\n\n## Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm run dev` | Start development server |\n| `npm run build` | Production build |\n| `npm run preview` | Preview production build |\n| `npm run check` | TypeScript/Svelte type checking |\n| `python scripts/build.py` | Build all content (smart mode) |\n| `python scripts/build.py --all` | Rebuild all versions |\n| `python scripts/build-indexes.py` | Regenerate search/crossref indexes |\n| `python scripts/build-embeddings.py` | Generate semantic search embeddings |\n| `python scripts/rebuild-manifests.py` | Update notebook metadata without re-execution |\n\n---\n\n## Design System\n\nGlobal styles in `app.css` with CSS custom properties:\n\n### Colors\n\n| Variable | Dark | Light |\n|----------|------|-------|\n| `--surface` | #08080c | #f0f0f4 |\n| `--surface-raised` | #1c1c26 | #ffffff |\n| `--text` | #f0f0f5 | #1a1a1f |\n| `--accent` | #0070c0 | #0070c0 |\n\n### Typography\n\n- **UI Font**: Inter\n- **Code Font**: JetBrains Mono\n- **Sizes**: 12px (base), 14px (md), 16px (lg)\n\n### Components\n\n- `.panel`, `.tile`, `.card` - Container styles\n- `.elevated` - Subtle shadow effect\n- `.crossref` - Cross-reference link styling\n\n---\n\n## Deployment\n\nGitHub Pages deployment via GitHub Actions.\n\n### Workflow\n\n1. Clone PathSim repositories\n2. Run `python scripts/build.py --all` (extracts API, notebooks, builds indexes)\n3. Build SvelteKit (`npm run build`)\n4. Deploy to GitHub Pages\n\n### Scheduled Builds\n\nDocumentation is automatically rebuilt on a schedule to pick up new package releases:\n\n- **Trigger**: GitHub Actions cron schedule (configurable)\n- **Smart builds**: Only processes new git tags not already in static/\n- **Auto-deploy**: New versions appear without manual intervention\n\n### Environment Variables\n\n- `BASE_PATH`: URL base path (e.g., `/pathsim-docs`)\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathsim%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpathsim%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathsim%2Fdocs/lists"}