selfdoc 0.3.1

Code-aware static site generator with directive-based content extraction

selfdoc

Code-aware static site generator that resolves :::directive blocks in Markdown templates into live content extracted from your source code.

Supports Python, Go, and TypeScript/JavaScript. Zero runtime dependencies -- pure Python stdlib.

Install

pip install selfdoc

or via npm (delegates to Python under the hood):

npm install -g selfdoc

Requires Python 3.11+.

Quick start

# Initialize in an existing project (auto-detects language)
selfdoc init

# Edit docs/index.md -- add directives referencing your code
# (see Directive syntax below)

# Build HTML output
selfdoc build

# Serve locally with live reload
selfdoc serve

Directive syntax

Directives are fenced blocks in your Markdown templates. They get replaced with content extracted from your source code at build time.

:::name arg
:::

Everything between :::name arg and the closing ::: is the directive body (optional, depends on the directive). Directives inside fenced code blocks are ignored.

Built-in directives

Directive	Arg	Description
module	dotted.path or file path	Extract module/package docstrings, exported functions, classes
schema	file.json or module ClassName	Extract dataclass fields or JSON keys as a table
test	file_path [TestName]	Embed test source code (whole file or specific function/class)
cli	module path	Extract CLI help/usage text and flag definitions
config	file path	Render JSON/TOML config files as key-value tables

Example -- embed the API docs for a Python module:

## API Reference

:::module selfdoc.config
:::

Example -- show a JSON schema as a table:

:::schema selfdoc.json
:::

Custom directives

Register custom directives in selfdoc.json under the directives key. Each entry maps a directive name to a Python script (relative to project root) that exports a resolve(arg, config) function returning a Markdown string.

{
  "directives": {
    "changelog": "scripts/changelog_directive.py"
  }
}

Script interface:

def resolve(arg: str, config: dict) -> str:
    """Return Markdown string to replace the directive block."""
    ...

Use in templates:

:::changelog v1.0.0
:::

Custom directives take priority over built-in names.

Configuration

selfdoc.json at the project root:

{
  "language": "python",
  "source": ["selfdoc/"],
  "docs": "docs/",
  "output": "docs/_build/",
  "deploy": {
    "provider": "cloudflare-pages",
    "project": "my-docs"
  },
  "directives": {}
}

Field	Required	Default	Description
language	yes	--	python, go, typescript, or javascript
source	yes	--	List of source directories to scan
docs	no	docs/	Directory containing Markdown templates
output	no	docs/_build/	Directory for generated HTML output
deploy	no	--	Deploy provider config (see Deploy below)
directives	no	{}	Custom directive script mappings

selfdoc init auto-detects language and source paths from project files (pyproject.toml, go.mod, tsconfig.json, package.json).

Commands

Command	Description
selfdoc init	Initialize selfdoc in the current project (creates selfdoc.json + starter template)
selfdoc build	Resolve directives and generate HTML to the output directory
selfdoc serve [--port PORT]	Serve built docs locally with SSE-based live reload (default port 8000)
selfdoc deploy	Deploy docs to the configured provider
selfdoc check	Validate all directives resolve successfully; report documentation coverage

Deploy

Cloudflare Pages

Requires the Wrangler CLI installed and authenticated.

{
  "deploy": {
    "provider": "cloudflare-pages",
    "project": "my-docs-project"
  }
}

selfdoc build && selfdoc deploy

GitHub Pages

Pushes the output directory to the gh-pages branch via force-push.

{
  "deploy": {
    "provider": "github-pages"
  }
}

Enable GitHub Pages in your repo settings (source: gh-pages branch).

Integration with rlsbl

When rlsbl detects a selfdoc.json in the project, it can trigger selfdoc build and selfdoc deploy as part of the release lifecycle via the .rlsbl/hooks/post-release.sh hook.

License

MIT