Add mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+      - name: Setup environment
+        uses: ./.github/actions/environment
+        with:
+          app-id: ${{ secrets.CI_BOT_ID }}
+          private-key: ${{ secrets.CI_BOT_KEY }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen --group docs
+
+      - name: Build documentation
+        run: |
+          uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          publish_dir: ./site
+          publish_branch: gh-pages

.gitignore

@@ -8,3 +8,5 @@ wheels/
 
 # Virtual environments
 .venv
+
+site/

docs/_static/custom_css.css

@@ -0,0 +1,178 @@
+/* Fix /page#foo going to the top of the viewport and being hidden by the navbar */
+html {
+    scroll-padding-top: 50px;
+}
+
+.md-header__button.md-logo img {
+    height: 1.8rem;  /* adjust as needed */
+}
+
+/* Fit the Twitter handle alongside the GitHub one in the top right. */
+
+div.md-header__source {
+    width: revert;
+    max-width: revert;
+}
+
+a.md-source {
+    display: inline-block;
+}
+
+.md-source__repository {
+    max-width: 100%;
+}
+
+/* Emphasise sections of nav on left hand side */
+
+nav.md-nav {
+  padding-left: 5px;
+}
+
+nav.md-nav--secondary {
+    border-left: revert !important;
+}
+
+.md-nav__title {
+  font-size: 0.9rem;
+}
+
+.md-nav__item--section > .md-nav__link {
+  font-size: 0.9rem;
+}
+
+/* Indent autogenerated documentation */
+
+div.doc-contents {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+}
+
+/* Increase visibility of splitters "---" */
+
+[data-md-color-scheme="default"] .md-typeset hr {
+    border-bottom-color: rgb(0, 0, 0);
+    border-bottom-width: 1pt;
+}
+
+[data-md-color-scheme="slate"] .md-typeset hr {
+    border-bottom-color: rgb(230, 230, 230);
+}
+
+/* More space at the bottom of the page */
+
+.md-main__inner {
+  margin-bottom: 1.5rem;
+}
+
+/* Remove prev/next footer buttons */
+
+.md-footer__inner {
+    display: none;
+}
+
+/* Change font sizes */
+
+html {
+    /* Decrease font size for overall webpage
+       Down from 137.5% which is the Material default */
+    font-size: 110%;
+}
+
+.md-typeset .admonition {
+    /* Increase font size in admonitions */
+    font-size: 100% !important;
+}
+
+.md-typeset details {
+    /* Increase font size in details */
+    font-size: 100% !important;
+}
+
+.md-typeset h1 {
+    font-size: 1.6rem;
+}
+
+.md-typeset h2 {
+    font-size: 1.5rem;
+}
+
+.md-typeset h3 {
+    font-size: 1.3rem;
+}
+
+.md-typeset h4 {
+    font-size: 1.1rem;
+}
+
+.md-typeset h5 {
+    font-size: 0.9rem;
+}
+
+.md-typeset h6 {
+    font-size: 0.8rem;
+}
+
+/* Bugfix: remove the superfluous parts generated when doing:
+
+??? Blah
+
+    ::: library.something
+*/
+
+.md-typeset details .mkdocstrings > h4 {
+    display: none;
+}
+
+.md-typeset details .mkdocstrings > h5 {
+    display: none;
+}
+
+/* Change default colours for <a> tags */
+
+[data-md-color-scheme="default"] {
+    --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+[data-md-color-scheme="slate"] {
+    --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+
+/* Highlight functions, classes etc. type signatures. Really helps to make clear where
+   one item ends and another begins. */
+
+[data-md-color-scheme="default"] {
+    --doc-heading-color: #DDD;
+    --doc-heading-border-color: #CCC;
+    --doc-heading-color-alt: #F0F0F0;
+}
+[data-md-color-scheme="slate"] {
+    --doc-heading-color: rgb(25,25,33);
+    --doc-heading-border-color: rgb(25,25,33);
+    --doc-heading-color-alt: rgb(33,33,44);
+    --md-code-bg-color: rgb(38,38,50);
+}
+
+h4.doc-heading {
+    /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/
+    background-color: var(--doc-heading-color);
+    border: solid var(--doc-heading-border-color);
+    border-width: 1.5pt;
+    border-radius: 2pt;
+    padding: 0pt 5pt 2pt 5pt;
+}
+h5.doc-heading, h6.heading {
+    background-color: var(--doc-heading-color-alt);
+    border-radius: 2pt;
+    padding: 0pt 5pt 2pt 5pt;
+}
+
+/* Make errors in notebooks have scrolling */
+.output_error > pre {
+    overflow: auto;
+}
+
+@font-face {
+    font-family: 'Ingeo';
+    src: url('./fonts/Ingeo-SemiBold.ttf') format('truetype');
+    font-weight: 600;
+    font-style: normal;
+}

docs/api-reference/cli.md

@@ -0,0 +1,65 @@
+# CLI API
+
+Command-line interface functions.
+
+## Overview
+
+The CLI module provides the `parse_cli()` function for easy command-line integration.
+
+## parse_cli()
+
+Parse configuration from command-line arguments:
+
+```python
+import fiddledyn as dyn
+import fiddle as fdl
+
+# Parse and build
+config = dyn.parse_cli()
+obj = fdl.build(config)
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# main.py
+import fiddledyn as dyn
+import fiddle as fdl
+
+config = dyn.parse_cli()
+obj = fdl.build(config)
+```
+
+Run with:
+
+```bash
+python main.py -f config.yaml model.lr=0.001
+```
+
+### With Custom Processing
+
+```python
+config = dyn.parse_cli()
+
+# Apply custom transformations
+if config.get('debug'):
+    # Enable debug mode
+    pass
+
+obj = fdl.build(config)
+```
+
+## Command-Line Syntax
+
+- `-f config.yaml` - Load configuration file
+- `key=value` - Override parameter value
+- `key=@file.yaml` - Load value from file
+
+## See Also
+
+- [CLI Overrides](../features/cli-overrides.md)
+- [Quick Start](../getting-started/quick-start.md)
+
+

docs/api-reference/core.md

@@ -0,0 +1,38 @@
+# Core API
+
+Core components of FiddleDyn for managing configuration state and references.
+
+## Overview
+
+The core module provides the fundamental building blocks for FiddleDyn:
+
+- **ParserContext** - Manages state during parsing including registry and references
+- **Reference** - Represents DAG references with IDs
+- **Types** - Core type definitions
+
+## ParserContext
+
+The `ParserContext` class tracks state during configuration parsing:
+
+```python
+from fiddledyn.core import ParserContext
+
+ctx = ParserContext()
+ctx.registry["key"] = "value"  # Add to registry
+```
+
+### Methods
+
+- `registry` - Dictionary for storing placeholder values
+- `references` - Dictionary for tracking DAG references
+
+## Key Classes
+
+See the source code in `src/fiddledyn/core/` for detailed implementation.
+
+## See Also
+
+- [Getting Started](../getting-started/installation.md)
+- [Basic Concepts](../getting-started/basic-concepts.md)
+
+