marimo-dev 0.1.14__tar.gz → 0.2.2__tar.gz

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/PKG-INFO

@@ -1,15 +1,21 @@
 Metadata-Version: 2.3
 Name: marimo-dev
-Version: 0.1.14
+Version: 0.2.2
 Summary: Build and publish python packages from marimo notebooks
 Author: Deufel
 Author-email: Deufel <MDeufel13@gmail.com>
 License: MIT
 Requires-Dist: fastcore>=1.10.0
+Requires-Dist: ipython>=9.8.0
+Requires-Dist: marimo>=0.19.7
+Requires-Dist: mohtml>=0.1.11
+Requires-Dist: pydantic-ai-slim>=1.50.0
+Requires-Dist: pytest>=9.0.2
 Requires-Dist: python-fasthtml>=0.12.37
 Requires-Dist: youtube-transcript-api>=1.2.3
 Requires-Python: >=3.12
 Project-URL: Repository, https://github.com/deufel/m-dev
+Project-URL: PyPI, https://pypi.org/project/marimo-dev/
 Description-Content-Type: text/markdown
 
 
@@ -87,7 +93,8 @@ from .core import greet
 
 ## What gets exported
 
-Only self-contained functions and classes are exported. A self-contained function must: reference no variables outside its scope (except from the setup cell), and be the only function in its cell. See [reusing functions](https://docs.marimo.io/guides/reusing_functions/) for details. Everything else - test code, UI elements, exploratory cells - stays in your notebooks.
+ 1. constants in setup cells
+ 2. [self-contained functions and classes](https://docs.marimo.io/guides/reusing_functions/)
 
 ## Hash pipe directives
 
@@ -101,12 +108,12 @@ def helper():
 
 @app.function
 #| internal
-def _private(): 
+def private(): 
     pass  # not added to __all__
 
 @app.function
 #| nodoc internal
-def _helper(): 
+def helper(): 
     pass  # neither exported nor documented
 ```
 
@@ -142,13 +149,14 @@ skip_prefixes = ["XX_", "test_"]  # ignore these files
 ## Commands
 
 ```bash
-md build              # build package from notebooks
+md build              # build package from notebooks and make docs
+md docs               # build the static docs (beta)
 md publish --test     # publish to Test PyPI
 md publish            # publish to PyPI
 md tidy               # remove __pycache__ and cache files
 md nuke               # remove all build artifacts (dist, docs, src, temp*)
 ```
-If you make a temp folder it will be explicitly removed when running `md nuke`
+*If you make a temp folder it will be explicitly removed when running `md nuke`*
 
 ## Dependencies
 

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/README.md

@@ -73,7 +73,8 @@ from .core import greet
 
 ## What gets exported
 
-Only self-contained functions and classes are exported. A self-contained function must: reference no variables outside its scope (except from the setup cell), and be the only function in its cell. See [reusing functions](https://docs.marimo.io/guides/reusing_functions/) for details. Everything else - test code, UI elements, exploratory cells - stays in your notebooks.
+ 1. constants in setup cells
+ 2. [self-contained functions and classes](https://docs.marimo.io/guides/reusing_functions/)
 
 ## Hash pipe directives
 
@@ -87,12 +88,12 @@ def helper():
 
 @app.function
 #| internal
-def _private(): 
+def private(): 
     pass  # not added to __all__
 
 @app.function
 #| nodoc internal
-def _helper(): 
+def helper(): 
     pass  # neither exported nor documented
 ```
 
@@ -128,13 +129,14 @@ skip_prefixes = ["XX_", "test_"]  # ignore these files
 ## Commands
 
 ```bash
-md build              # build package from notebooks
+md build              # build package from notebooks and make docs
+md docs               # build the static docs (beta)
 md publish --test     # publish to Test PyPI
 md publish            # publish to PyPI
 md tidy               # remove __pycache__ and cache files
 md nuke               # remove all build artifacts (dist, docs, src, temp*)
 ```
-If you make a temp folder it will be explicitly removed when running `md nuke`
+*If you make a temp folder it will be explicitly removed when running `md nuke`*
 
 ## Dependencies
 

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/pyproject.toml

@@ -4,12 +4,17 @@ build-backend = "uv_build"
 
 [project]
 name = "marimo-dev"
-version = "0.1.14"
+version = "0.2.2"
 description = "Build and publish python packages from marimo notebooks"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "fastcore>=1.10.0",
+    "ipython>=9.8.0",
+    "marimo>=0.19.7",
+    "mohtml>=0.1.11",
+    "pydantic-ai-slim>=1.50.0",
+    "pytest>=9.0.2",
     "python-fasthtml>=0.12.37",
     "youtube-transcript-api>=1.2.3",
 ]
@@ -34,6 +39,8 @@ classifiers = [
 
 [project.urls]
 Repository = "https://github.com/deufel/m-dev"
+PyPI = "https://pypi.org/project/marimo-dev/"
+
 
 # Marimo-Dev settings
 [tool.marimo-dev]
@@ -44,7 +51,7 @@ Repository = "https://github.com/deufel/m-dev"
   skip_prefixes = ["XX_", "test_"]
 
 # Remove this when ready to upload this is a saftey net for not accidentally uploading
-# classifiers = ["Private :: Do Not Upload"]
+classifiers = ["Private :: Do Not Upload"]
 
 # Development packages
 [dependency-groups]

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/src/marimo_dev/__init__.py

@@ -1,26 +1,33 @@
 """Build and publish python packages from marimo notebooks"""
-__version__ = '0.1.14'
+__version__ = '0.2.2'
 __author__ = 'Deufel'
 from .core import Config, read_config, Kind, Param, Node
 from .read import inline_doc, parse_params, parse_hash_pipe, parse_class_params, parse_class_methods, parse_ret, src_with_decs, is_export, parse_import, parse_const, parse_export, parse_node, parse_file, read_meta, nb_name, scan
 from .pkg import clean, write, write_mod, rewrite_imports, write_init
-from .docs import cls_sig, fn_sig, sig, write_llms
-from .build import build, tidy, nuke
+from .docs import cls_sig, fn_sig, sig, write_llms, exp_type, render_param, nb_path, render_node, render_module_page, build_docs, export_wasm, write_nojekyll, html_preview, render_index_page, Icon
+from .build import build, tidy, nuke, get_pypi_name, extract_import_names, pep723_header, bundle
 from .publish import publish
-from .cli import main
 __all__ = [
     "Config",
+    "Icon",
     "Kind",
     "Node",
     "Param",
     "build",
+    "build_docs",
+    "bundle",
     "clean",
     "cls_sig",
+    "exp_type",
+    "export_wasm",
+    "extract_import_names",
     "fn_sig",
+    "get_pypi_name",
+    "html_preview",
     "inline_doc",
     "is_export",
-    "main",
     "nb_name",
+    "nb_path",
     "nuke",
     "parse_class_methods",
     "parse_class_params",
@@ -32,9 +39,14 @@ __all__ = [
     "parse_node",
     "parse_params",
     "parse_ret",
+    "pep723_header",
     "publish",
     "read_config",
     "read_meta",
+    "render_index_page",
+    "render_module_page",
+    "render_node",
+    "render_param",
     "rewrite_imports",
     "scan",
     "sig",
@@ -44,4 +56,5 @@ __all__ = [
     "write_init",
     "write_llms",
     "write_mod",
+    "write_nojekyll",
 ]

marimo_dev-0.2.2/src/marimo_dev/build.py

@@ -0,0 +1,98 @@
+from .core import Kind, Param, Node, Config, read_config
+from .read import scan, read_meta
+from .pkg import write_mod, write_init, clean
+from .docs import write_llms
+from pathlib import Path
+import ast, shutil, re
+
+IMPORT_TO_PYPI = {'bs4': 'beautifulsoup4', 'PIL': 'pillow', 'cv2': 'opencv-python', 'sklearn': 'scikit-learn', 'yaml': 'pyyaml'}
+
+def build(
+    root='.',  # root directory containing pyproject.toml
+)->str:        # path to built package
+    "Build a Python package from notebooks."
+    cfg = read_config(root)
+    meta, mods = scan(root)
+    mod_names = [name for name, _ in mods]
+    pkg = Path(root) / cfg.out / meta['name'].replace('-', '_')
+    if pkg.exists(): shutil.rmtree(pkg)
+    pkg.mkdir(parents=True, exist_ok=True)
+    for name, nodes in mods:
+        stripped = re.sub(r'^[a-z]_', '', name)
+        if stripped != 'index' and any(n.kind == Kind.EXP for n in nodes): write_mod(pkg/f'{stripped}.py', nodes, mod_names)
+    write_init(pkg/'__init__.py', meta, mods)
+    all_exp = [n for _, nodes in mods for n in nodes if n.kind == Kind.EXP]
+    if all_exp: write_llms(meta, all_exp)
+    return str(pkg)
+
+def tidy():
+    "Remove cache and temporary files (__pycache__, __marimo__, .pytest_cache, etc)."
+    import shutil
+    for p in Path('.').rglob('__pycache__'): shutil.rmtree(p, ignore_errors=True)
+    for p in Path('.').rglob('__marimo__'): shutil.rmtree(p, ignore_errors=True)
+    for p in Path('.').rglob('.pytest_cache'): shutil.rmtree(p, ignore_errors=True)
+    for p in Path('.').rglob('*.pyc'): p.unlink(missing_ok=True)
+    print("Cleaned cache files")
+
+def nuke():
+    "Remove all build artifacts (dist, docs, src) and cache files."
+    import shutil
+    tidy()
+    for d in ['dist', 'docs', 'src', 'temp']: shutil.rmtree(d, ignore_errors=True)
+    print("Nuked build artifacts")
+
+def get_pypi_name(import_name):
+    "Map import name to PyPI package name."
+    root = import_name.split('.')[0]
+    return IMPORT_TO_PYPI.get(root, root)
+
+def extract_import_names(nodes):
+    "Extract top-level module names from import nodes."
+    names = set()
+    for n in nodes:
+        if n.kind != Kind.IMP: continue
+        tree = ast.parse(n.src)
+        for stmt in ast.walk(tree):
+            if isinstance(stmt, ast.Import):
+                for alias in stmt.names:
+                    names.add(alias.name.split('.')[0])
+            elif isinstance(stmt, ast.ImportFrom) and stmt.module:
+                names.add(stmt.module.split('.')[0])
+    return names
+
+def pep723_header(deps):
+    "Generate PEP 723 inline script metadata."
+    deps_str = ', '.join(f'"{d}"' for d in sorted(deps))
+    return f'# /// script\n# dependencies = [{deps_str}]\n# ///\n'
+
+def bundle(root='.', name=None):
+    "Bundle all notebooks into a single Python file with PEP 723 dependencies."
+    cfg = read_config(root)
+    meta, mods = scan(root)
+    
+    # Collect all nodes
+    all_nodes = [n for _, nodes in mods for n in nodes]
+    
+    # Extract dependencies
+    import_names = extract_import_names(all_nodes)
+    # Filter out stdlib and local modules
+    mod_names = [m for m, _ in mods]
+    external = {get_pypi_name(n) for n in import_names if n not in mod_names}
+    
+    # Build output
+    header = pep723_header(external)
+    imports = '\n'.join(n.src for n in all_nodes if n.kind == Kind.IMP)
+    consts = '\n'.join(n.src for n in all_nodes if n.kind == Kind.CONST)
+    exports = '\n\n'.join(clean(n.src) for n in all_nodes if n.kind == Kind.EXP)
+    
+    content = '\n\n'.join(p for p in [header, imports, consts, exports] if p.strip())
+    
+    # Determine output path
+    if name:
+        out_path = Path(root) / name
+    else:
+        out_path = Path(root) / cfg.out / meta['name'] / '__init__.py'
+    
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(content)
+    return f"Bundled to {out_path}"

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/src/marimo_dev/core.py

@@ -44,3 +44,4 @@ class Node:
     ret: tuple[str,str]|None = None
     hash_pipes: list[str] = field(default_factory=list)
     module: str = ''
+    lineno: int = 0

marimo_dev-0.2.2/src/marimo_dev/docs.py

@@ -0,0 +1,238 @@
+from .core import Kind, Param, Node, Config, read_config
+from .read import scan, nb_name, read_meta
+from pathlib import Path
+import ast, re, os
+import marimo as mo
+from functools import partial
+from fastcore.xml import Span, Code, Li, Article, Div, Ul, P, FT, to_xml, Pre, Link, A, Iframe, Button, H1, H2, H3, Nav, Aside, Header, Input, NotStr, Strong, Main
+from fasthtml.components import ft, Html, Head, Script, Body, show, Style, Title
+
+icons = {'home': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-house-icon lucide-house"><path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8"/><path d="M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>', 'pypi': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-blocks-icon lucide-blocks"><path d="M10 22V7a1 1 0 0 0-1-1H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-5a1 1 0 0 0-1-1H2"/><rect x="14" y="2" width="8" height="8" rx="1"/></svg>', 'menu': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-menu-icon lucide-menu"><path d="M4 5h16"/><path d="M4 12h16"/><path d="M4 19h16"/></svg>', 'x': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x-icon lucide-x"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>', 'github': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github-icon lucide-github"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"/><path d="M9 18c-4.51 2-5-2-7-2"/></svg>', 'code': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-code-icon lucide-code"><path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/></svg>', 'info': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-info-icon lucide-info"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>', 'calendar': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-calendar1-icon lucide-calendar-1"><path d="M11 14h1v4"/><path d="M16 2v4"/><path d="M3 10h18"/><path d="M8 2v4"/><rect x="3" y="4" width="18" height="18" rx="2"/></svg>', 'circle-x': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-x-icon lucide-circle-x"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/></svg>', 'external-link': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-external-link-icon lucide-external-link"><path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></svg>'}
+
+def cls_sig(
+    n:Node,           # the node to generate signature for
+    dataclass=False,  # whether to include @dataclass decorator
+)->str:               # formatted class signature
+    "Generate a class signature string."
+    header = f"@dataclass\nclass {n.name}:" if dataclass else f"class {n.name}:"
+    lines = [header]
+    if n.doc: lines.append(f'    """{n.doc}"""')
+    for p in n.params:
+        attr = f"    {p.name}{f': {p.anno}' if p.anno else ''}{f' = {p.default}' if p.default else ''}"
+        if p.doc: attr += f"  # {p.doc}"
+        lines.append(attr)
+    for m in n.methods:
+        ps = ', '.join(f"{p.name}{f': {p.anno}' if p.anno else ''}{f'={p.default}' if p.default else ''}" for p in m['params'])
+        ret = f" -> {m['ret'][0]}" if m['ret'] else ""
+        lines.append(f"    def {m['name']}({ps}){ret}:")
+        if m['doc']: lines.append(f'        """{m["doc"]}"""')
+    return '\n'.join(lines)
+
+def fn_sig(
+    n: Node,        # the node to generate signature for
+    is_async=False  # async ?
+)->str:             # formatted signature string
+    "Generate a function signature string with inline parameter documentation."
+    prefix = 'async def' if is_async else 'def'
+    ret = f" -> {n.ret[0]}" if n.ret else ""
+    if not n.params:
+        sig = f"{prefix} {n.name}(){ret}:"
+        return f'{sig}\n    """{n.doc}"""' if n.doc else sig
+    params = [f"    {p.name}{f': {p.anno}' if p.anno else ''}{f'={p.default}' if p.default else ''},{f'  # {p.doc}' if p.doc else ''}" for p in n.params]
+    params[-1] = params[-1].replace(',', '')
+    lines = [f"{prefix} {n.name}("] + params + [f"){ret}:"]
+    if n.doc: lines.append(f'    """{n.doc}"""')
+    return '\n'.join(lines)
+
+def sig(
+    n:Node, # the node to generate signature for
+)->str:     # formatted signature string
+    "Generate a signature string for a class or function node."
+    t = exp_type(n)
+    if t == 'class': return cls_sig(n, dataclass=n.src.lstrip().startswith('@dataclass'))
+    return fn_sig(n, is_async=t == 'async')
+
+def write_llms(
+    meta: dict,    # project metadata from pyproject.toml
+    nodes: list,   # list of Node objects to document
+    root: str='.'  # root directory containing pyproject.toml
+):
+    "Write API signatures to llms.txt file for LLM consumption."
+    cfg = read_config(root)
+    sigs = '\n\n'.join(sig(n) for n in nodes if not n.name.startswith('__') and 'nodoc' not in n.hash_pipes)
+    content = f"# {meta['name']}\n\n> {meta['desc']}\n\nVersion: {meta['version']}\n\n## API\n\n```python\n{sigs}\n```"
+    Path(cfg.docs).mkdir(exist_ok=True)
+    (Path(cfg.docs)/'llms.txt').write_text(content)
+
+def exp_type(n):
+    if n.methods or 'class ' in n.src: return 'class'
+    if n.src.lstrip().startswith('async def'): return 'async'
+    return 'func'
+
+def render_param(p):
+    parts = [Code(p.name)]
+    if p.anno: parts.append(Span(f": {p.anno}", style="color: #666;"))
+    if p.default: parts.append(Span(f" = {p.default}", style="color: #888;"))
+    if p.doc: parts.append(Span(f" — {p.doc}", style="color: #555; font-style: italic;"))
+    return Li(*parts)
+
+def nb_path(
+    mod_name, 
+    root='.'
+):
+    '''[TODO] '''
+    cfg = read_config(root)
+    for f in (Path(root) / cfg.nbs).glob('*.py'):
+        if nb_name(f, root) == mod_name: return f.relative_to(root)
+    return None
+
+def render_node(
+    n, 
+    repo_url=None, 
+    root='.'
+):
+    '''Builds a `node` for docs'''
+    t = exp_type(n)
+    signature = sig(n)
+    lines = signature.split('\n')
+    line_nums = '\n'.join(str(i+1) for i in range(len(lines)))
+    node_id = f"code-{n.module}-{n.name}"
+    tag_colors = {'func': '#10b981', 'async': '#f59e0b', 'class': '#8b5cf6'}
+    tag = Span(t, style=f"padding: 0.25rem 0.6rem; border-radius: 4px; font-size: 0.75rem; font-weight: 600; background: {tag_colors.get(t, '#666')}; color: white;")
+    full_name = Span(Span(f"{n.module}.", style="color: #666;"), Span(n.name, style="color: #e5e5e5;"), style="font-weight: 500; font-size: 1rem; margin-left: 0.75rem;") if n.module else Span(n.name, style="font-weight: 500; font-size: 1rem; color: #e5e5e5; margin-left: 0.75rem;")
+    nb = nb_path(n.module, root)
+    btn_style = "display: flex; align-items: center; gap: 0.25rem; background: #333; border: 1px solid #444; color: #ccc; padding: 0.25rem 0.5rem; border-radius: 4px; cursor: pointer; font-size: 0.75rem;"
+    link_style = "text-decoration: none;"
+    copy_btn = Button("📋", onclick=f"navigator.clipboard.writeText(document.getElementById('{node_id}').textContent).then(() => this.textContent = '✓').then(() => setTimeout(() => this.textContent = '📋', 1500))", style="background: transparent; border: none; cursor: pointer; font-size: 0.9rem; padding: 0.25rem;")
+    source_btn = A(Button(Icon('github', size=16), "Source", style=btn_style), href=f"{repo_url}/blob/master/{nb}#L{n.lineno}", target="_blank", style=link_style) if repo_url and nb and n.lineno else None
+    edit_btn = A(Button(Icon('code', size=16), "Edit", style=btn_style), href=f"{repo_url}/edit/master/{nb}", target="_blank", style=link_style) if repo_url and nb else None
+    blame_btn = A(Button(Icon('info', size=16), "Blame", style=btn_style), href=f"{repo_url}/blame/master/{nb}#L{n.lineno}", target="_blank", style=link_style) if repo_url and nb and n.lineno else None
+    history_btn = A(Button(Icon('calendar', size=16), "History", style=btn_style), href=f"{repo_url}/commits/master/{nb}", target="_blank", style=link_style) if repo_url and nb else None
+    issue_btn = A(Button(Icon('circle-x', size=16), "Issue", style=btn_style), href=f"{repo_url}/issues/new?title=Issue%20with%20{n.name}&body=Found%20in%20{nb}%23L{n.lineno}", target="_blank", style=link_style) if repo_url and nb else None
+    header = Div(
+        Div(tag, full_name, style="display: flex; align-items: center;"),
+        Div(copy_btn, source_btn, edit_btn, blame_btn, history_btn, issue_btn, style="display: flex; align-items: center; gap: 0.5rem;"),
+        style="display: flex; justify-content: space-between; align-items: center; padding: 0.75rem 1rem;")
+    doc_line = P(n.doc, style="margin: 0; padding: 0 1rem 0.5rem 1rem; color: #888; font-size: 0.85rem;") if n.doc else None
+    code_block = Div(
+        Pre(Code(line_nums), style="margin: 0; padding: 0; color: #555; text-align: right; user-select: none; font-size: 0.8rem; line-height: 1.6;"),
+        Pre(Code(signature, cls="language-python", id=node_id), style="margin: 0; padding: 0; flex: 1; overflow-x: auto; font-size: 0.8rem; line-height: 1.6;"),
+        style="display: flex; background: #1a1a1a; border-top: 1px solid #2a2a2a;")
+    return Article(header, doc_line, code_block, style="margin-bottom: 0.75rem; border-radius: 8px; overflow: hidden; background: #1e1e1e;")
+
+def render_module_page(
+    mod_name, 
+    mod_nodes, 
+    all_mod_names, 
+    meta, 
+    root='.'):
+    '''Builds a Module Page'''
+    repo_url = meta.get('urls', {}).get('Repository')
+    exp_nodes = [n for n in mod_nodes if n.kind == Kind.EXP]
+    content = Div(*[render_node(n, repo_url, root) for n in exp_nodes], style="padding: 1rem; background: #121212; overflow-y: auto;")
+    head_elements = [
+        Script(type="module", src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.0-RC.7/bundles/datastar.js"),
+        Link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/vs2015.min.css"),
+        Script(src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"),
+        Script("hljs.highlightAll();"),
+        Style("body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; } code { font-family: 'SF Mono', Consolas, monospace; }"),
+        Title(f"{mod_name} - {meta['name']}")]
+    search_input = Input(type="text", placeholder="Search...", style="width: 100%; padding: 0.5rem; border: 1px solid #333; border-radius: 4px; background: #252525; color: #fff; margin-bottom: 1rem;", **{"data-bind": "search"})
+    nav_links = [Li(A("← Index", href="index.html", style="color: #888; text-decoration: none; font-size: 0.85rem;"))] + [Li(A(m, href=f"{m}.html", style=f"color: {'#fff' if m == mod_name else '#aaa'}; text-decoration: none;")) for m in all_mod_names]
+    nav = Nav(
+        H3(meta['name'], style="margin: 0 0 1rem 0; color: #fff;"),
+        search_input,
+        Ul(*nav_links, style="list-style: none; padding: 0; margin: 0;"),
+        style="padding: 1rem; background: #1a1a1a; min-width: 180px;")
+    btn_style = "display: flex; align-items: center; gap: 0.25rem; background: #333; border: 1px solid #444; color: #ccc; padding: 0.5rem 0.75rem; border-radius: 4px; cursor: pointer; font-size: 0.85rem;"
+    wasm_btn = A(Button(Icon('external-link', size=16), "Run in Browser", style=btn_style), href=f"wasm/{mod_name}/index.html", target="_blank", style="text-decoration: none;")
+    header = Header(
+        Div(H1(mod_name, style="margin: 0; font-size: 1.5rem; color: #fff;"), wasm_btn, style="display: flex; align-items: center; justify-content: space-between;"),
+        style="padding: 1rem; background: #1e1e1e; border-bottom: 1px solid #333;")
+    body = Body(nav, Div(header, content, style="flex: 1; display: flex; flex-direction: column;"), style="display: flex; height: 100vh; margin: 0; background: #121212;", **{"data-signals": "{search: ''}"})
+    return Html(Head(*head_elements), body)
+
+def build_docs(
+    root='.'    # the project root (this should never really change)
+):
+    '''Builds the static documentation website'''
+    cfg = read_config(root)
+    meta = read_meta(root)
+    _, mods = scan(root)
+    mod_names = [name for name, _ in mods]
+    docs_path = Path(root) / cfg.docs
+    docs_path.mkdir(exist_ok=True)
+    (docs_path / "index.html").write_text(to_xml(render_index_page(meta, mods)))
+    for mod_name, mod_nodes in mods:
+        (docs_path / f"{mod_name}.html").write_text(to_xml(render_module_page(mod_name, mod_nodes, mod_names, meta, root)))
+    return f"Generated index + {len(mods)} module pages in {docs_path}"
+
+cfg = read_config(root)
+
+nbs_dir = Path(root) / cfg.nbs
+
+wasm_dir = Path(root) / cfg.docs / 'wasm'
+
+wasm_dir.mkdir(parents=True, exist_ok=True)
+
+for f in nbs_dir.glob('*.py'):
+    name = nb_name(f, root)
+    if name:
+        os.system(f'marimo export html-wasm {f} -o {wasm_dir}/{name} --mode edit')
+
+def write_nojekyll(root='.'):
+    cfg = read_config(root)
+    Path(root, cfg.docs, '.nojekyll').touch()
+
+def html_preview(width='100%', height='300px'):
+    "Display FT components in an IFrame"
+    def _preview(*components): show(Iframe(srcdoc=to_xml(components[0] if len(components) == 1 else Div(*components)), width=width, height=height))
+    return _preview
+
+def render_index_page(meta, mods, repo_url=None):
+    mod_names = [name for name, _ in mods]
+    head_elements = [
+        Script(type="module", src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.0-RC.7/bundles/datastar.js"),
+        Link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/vs2015.min.css"),
+        Script(src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"),
+        Script("hljs.highlightAll();"),
+        Style("body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; } code { font-family: 'SF Mono', Consolas, monospace; }"),
+        Title(meta['name'])]
+    nav_links = [Li(A(m, href=f"{m}.html", style="color: #aaa; text-decoration: none;")) for m in mod_names]
+    nav = Nav(
+        H3(meta['name'], style="margin: 0 0 1rem 0; color: #fff;"),
+        Ul(*nav_links, style="list-style: none; padding: 0; margin: 0;"),
+        style="padding: 1rem; background: #1a1a1a; min-width: 180px;")
+    module_cards = [A(Div(H3(name, style="margin: 0 0 0.5rem 0; color: #fff;"), P(f"{len([n for n in nodes if n.kind == Kind.EXP])} exports", style="margin: 0; color: #888;"), 
+        style="padding: 1rem; background: #1e1e1e; border-radius: 8px;"), href=f"{name}.html", style="text-decoration: none;") for name, nodes in mods]
+    content = Div(
+        H1(meta['name'], style="margin: 0 0 0.5rem 0; color: #fff;"),
+        P(meta['desc'], style="color: #888; margin: 0 0 2rem 0;"),
+        P(f"Version {meta['version']}", style="color: #666; margin: 0 0 2rem 0; font-size: 0.9rem;"),
+        H2("Modules", style="color: #fff; margin: 0 0 1rem 0; font-size: 1.2rem;"),
+        Div(*module_cards, style="display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1rem;"),
+        style="padding: 2rem; flex: 1;")
+    body = Body(nav, content, style="display: flex; min-height: 100vh; margin: 0; background: #121212;")
+    return Html(Head(*head_elements), body)
+
+def Icon(name: str,            # name of the icon MUST be in icon_dict
+         size=24,              # value to be passed to height and width of the icon
+         stroke=1.5,           # stroke width 
+         cls=None,             # css class
+         icon_dict:dict=icons, # Dict of icons {"name":"<svg...>"}
+         **kwargs              # passed to through to FT 
+        ) -> 'Any':            # Follow recomendation from fastHTML docs
+    '''
+    Creates a custom html compliant <icon-{name}>... 
+    Intended to be used with a Global Dict of icons {"home": "<svg...", "info": "<svg..."} 
+    Icon('home') -> <icon-home> ....  </icon-home>
+    '''
+    if name not in icon_dict: raise ValueError(f"Icon '{name}' not found")
+
+    # count=1 Replace only the first occurrence of width & height 99% of time this is what you want
+    svg_string = icon_dict[name]
+    svg_string = re.sub(r'width="\d+"', f'width="{size}"', svg_string, count=1)
+    svg_string = re.sub(r'height="\d+"', f'height="{size}"', svg_string, count=1)
+    svg_string = re.sub(r'stroke-width="\d+"', f'stroke-width="{stroke}"', svg_string)
+
+    return ft(f'icon-{name}', NotStr(svg_string), cls=cls, **kwargs)

{marimo_dev-0.1.14 → marimo_dev-0.2.2}/src/marimo_dev/read.py

@@ -92,15 +92,15 @@ def parse_const(
     n:ast.AST, # AST node to check
     ls:list,   # source lines (unused)
 )->Node|None:  # Node if constant assignment, else None
-    "Extract constant definition (dunder-prefixed, non-dunder-suffixed)."
+    "Extract constant definition from assignment."
     if not isinstance(n, ast.Assign): return None
     for t in n.targets:
-        if isinstance(t, ast.Name) and t.id.startswith('__') and not t.id.endswith('__'): return Node(Kind.CONST, t.id, ast.unparse(n))
+        if isinstance(t, ast.Name): return Node(Kind.CONST, t.id, ast.unparse(n))
 
 def parse_export(
     n:ast.AST,  # AST node to check
     ls:list,    # source lines for inline doc and decorators
-    cfg:Config, # configuration object
+    cfg:Config  # configuration object
 )->Node|None:   # Node if exported function/class, else None
     "Extract exported function or class decorated with export decorators from config."
     if not isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): return None
@@ -108,8 +108,8 @@ def parse_export(
     if not export_dec or n.name.startswith('test_'): return None
     doc,src = ast.get_docstring(n) or '', src_with_decs(n, ls)
     hash_pipes = parse_hash_pipe(ls, export_dec)
-    if isinstance(n, ast.ClassDef): return Node(Kind.EXP, n.name, src, doc, parse_class_params(n, ls), parse_class_methods(n, ls), None, hash_pipes)
-    return Node(Kind.EXP, n.name, src, doc, parse_params(n, ls), [], parse_ret(n, ls), hash_pipes)
+    if isinstance(n, ast.ClassDef): return Node(Kind.EXP, n.name, src, doc, parse_class_params(n, ls), parse_class_methods(n, ls), None, hash_pipes, '', n.lineno)
+    return Node(Kind.EXP, n.name, src, doc, parse_params(n, ls), [], parse_ret(n, ls), hash_pipes, '', n.lineno)
 
 def parse_node(
     n:ast.AST, # AST node to parse
@@ -118,10 +118,22 @@ def parse_node(
 ):             # yields Node objects for imports, constants, and exports
     "Extract importable nodes from an AST node."
     ls = src.splitlines()
+    
+    # Handle setup cells
     if isinstance(n, ast.With):
         for s in n.body:
             if (node := parse_import(s, ls)): yield node
             if (node := parse_const(s, ls)): yield node
+    
+    # Handle export-named cells (e.g. def export(): or def export_main():)
+    if isinstance(n, ast.FunctionDef) and n.name.startswith('export'):
+        body = [s for s in n.body if not isinstance(s, ast.Return)]
+        if body:
+            src = '\n\n'.join(ast.unparse(s) for s in body)
+            yield Node(Kind.EXP, n.name, src)
+            return
+    
+    # Handle decorated exports
     if (node := parse_export(n, ls, cfg)): yield node
 
 def parse_file(
@@ -138,13 +150,27 @@ def parse_file(
 
 def read_meta(
     root='.', # project root directory containing pyproject.toml
-)->dict:      # metadata dict with name, version, desc, license, author
+)->dict:      # metadata dict with name, version, desc, license, author, urls
     "Read project metadata from pyproject.toml."
-    with open(Path(root)/'pyproject.toml', 'rb') as f: p = tomllib.load(f).get('project', {})
+    with open(Path(root)/'pyproject.toml', 'rb') as f: 
+        p = tomllib.load(f).get('project', {})
+
+    # Extract author
     a = (p.get('authors') or [{}])[0]
     author = f"{a.get('name','')} <{a.get('email','')}>".strip(' <>') if isinstance(a, dict) else str(a)
+
+    # Extract license
     lic = p.get('license', {})
-    return dict(name=p.get('name',''), version=p.get('version','0.0.0'), desc=p.get('description',''), license=lic.get('text','') if isinstance(lic, dict) else lic, author=author)
+    license_text = lic.get('text','') if isinstance(lic, dict) else lic
+
+    return dict(
+        name=p.get('name',''),
+        version=p.get('version','0.0.0'),
+        desc=p.get('description',''),
+        license=license_text,
+        author=author,
+        urls=p.get('urls', {})
+    )
 
 def nb_name(
     f: Path,       # file path to extract notebook name from

marimo_dev-0.1.14/src/marimo_dev/build.py

@@ -1,40 +0,0 @@
-from .core import Kind, Param, Node, Config, read_config
-from .read import scan, read_meta
-from .pkg import write_mod, write_init
-from .docs import write_llms
-from pathlib import Path
-import ast, shutil, re
-
-def build(
-    root='.',  # root directory containing pyproject.toml
-)->str:        # path to built package
-    "Build a Python package from notebooks."
-    cfg = read_config(root)
-    meta, mods = scan(root)
-    mod_names = [name for name, _ in mods]
-    pkg = Path(root) / cfg.out / meta['name'].replace('-', '_')
-    if pkg.exists(): shutil.rmtree(pkg)
-    pkg.mkdir(parents=True, exist_ok=True)
-    for name, nodes in mods:
-        stripped = re.sub(r'^[a-z]_', '', name)
-        if stripped != 'index' and any(n.kind == Kind.EXP for n in nodes): write_mod(pkg/f'{stripped}.py', nodes, mod_names)
-    write_init(pkg/'__init__.py', meta, mods)
-    all_exp = [n for _, nodes in mods for n in nodes if n.kind == Kind.EXP]
-    if all_exp: write_llms(meta, all_exp)
-    return str(pkg)
-
-def tidy():
-    "Remove cache and temporary files (__pycache__, __marimo__, .pytest_cache, etc)."
-    import shutil
-    for p in Path('.').rglob('__pycache__'): shutil.rmtree(p, ignore_errors=True)
-    for p in Path('.').rglob('__marimo__'): shutil.rmtree(p, ignore_errors=True)
-    for p in Path('.').rglob('.pytest_cache'): shutil.rmtree(p, ignore_errors=True)
-    for p in Path('.').rglob('*.pyc'): p.unlink(missing_ok=True)
-    print("Cleaned cache files")
-
-def nuke():
-    "Remove all build artifacts (dist, docs, src) and cache files."
-    import shutil
-    tidy()
-    for d in ['dist', 'docs', 'src', 'temp']: shutil.rmtree(d, ignore_errors=True)
-    print("Nuked build artifacts")

marimo_dev-0.1.14/src/marimo_dev/cli.py

@@ -1,18 +0,0 @@
-from .build import build, tidy, nuke
-from .publish import publish
-import sys, subprocess
-from pathlib import Path
-
-def main():
-    if len(sys.argv) < 2: print("Usage: md [build|publish|tidy|nuke]"); sys.exit(1)
-    cmd = sys.argv[1]
-    if cmd == 'build':
-        print(f"Built package at: {build()}")
-    elif cmd == 'publish':
-        test = '--test' in sys.argv or '-t' in sys.argv
-        target = "TestPyPI" if test else "PyPI"
-        if input(f"Publish to {target}? [y/N] ").lower() != 'y': print("Aborted"); sys.exit(0)
-        publish(test=test)
-    elif cmd == 'tidy': tidy()
-    elif cmd == 'nuke': nuke()
-    else: print(f"Unknown command: {cmd}"); sys.exit(1)

marimo_dev-0.1.14/src/marimo_dev/docs.py

@@ -1,58 +0,0 @@
-from .core import Kind, Param, Node, Config, read_config
-from pathlib import Path
-import ast
-import marimo as mo
-from functools import partial
-
-def cls_sig(
-    n:Node,           # the node to generate signature for
-    dataclass=False,  # whether to include @dataclass decorator
-)->str:               # formatted class signature
-    "Generate a class signature string."
-    header = f"@dataclass\nclass {n.name}:" if dataclass else f"class {n.name}:"
-    lines = [header]
-    if n.doc: lines.append(f'    """{n.doc}"""')
-    for p in n.params:
-        attr = f"    {p.name}{f': {p.anno}' if p.anno else ''}{f' = {p.default}' if p.default else ''}"
-        if p.doc: attr += f"  # {p.doc}"
-        lines.append(attr)
-    for m in n.methods:
-        ps = ', '.join(f"{p.name}{f': {p.anno}' if p.anno else ''}{f'={p.default}' if p.default else ''}" for p in m['params'])
-        ret = f" -> {m['ret'][0]}" if m['ret'] else ""
-        lines.append(f"    def {m['name']}({ps}){ret}:")
-        if m['doc']: lines.append(f'        """{m["doc"]}"""')
-    return '\n'.join(lines)
-
-def fn_sig(n, is_async=False):
-    "Generate a function signature string with inline parameter documentation."
-    prefix = 'async def' if is_async else 'def'
-    ret = f" -> {n.ret[0]}" if n.ret else ""
-    if not n.params:
-        sig = f"{prefix} {n.name}(){ret}:"
-        return f'{sig}\n    """{n.doc}"""' if n.doc else sig
-    params = [f"    {p.name}{f': {p.anno}' if p.anno else ''}{f'={p.default}' if p.default else ''},{f'  # {p.doc}' if p.doc else ''}" for p in n.params]
-    params[-1] = params[-1].replace(',', '')
-    lines = [f"{prefix} {n.name}("] + params + [f"){ret}:"]
-    if n.doc: lines.append(f'    """{n.doc}"""')
-    return '\n'.join(lines)
-
-def sig(
-    n:Node, # the node to generate signature for
-)->str:     # formatted signature string
-    "Generate a signature string for a class or function node."
-    src = n.src.lstrip()
-    if n.methods or src.startswith('class ') or src.startswith('@dataclass'):
-        return cls_sig(n, dataclass=src.startswith('@dataclass'))
-    return fn_sig(n, is_async=src.startswith('async def'))
-
-def write_llms(
-    meta: dict,    # project metadata from pyproject.toml
-    nodes: list,   # list of Node objects to document
-    root: str='.'  # root directory containing pyproject.toml
-):
-    "Write API signatures to llms.txt file for LLM consumption."
-    cfg = read_config(root)
-    sigs = '\n\n'.join(sig(n) for n in nodes if not n.name.startswith('__') and 'nodoc' not in n.hash_pipes)
-    content = f"# {meta['name']}\n\n> {meta['desc']}\n\nVersion: {meta['version']}\n\n## API\n\n```python\n{sigs}\n```"
-    Path(cfg.docs).mkdir(exist_ok=True)
-    (Path(cfg.docs)/'llms.txt').write_text(content)