Metadata-Version: 2.4
Name: selfdoc
Version: 0.7.0
Summary: Code-aware static site generator with directive-based content extraction
Project-URL: Repository, https://github.com/smm-h/selfdoc
Author: smm-h
License-Expression: MIT
License-File: LICENSE
Keywords: docstring,documentation,jsdoc,rlsbl,selfdoc,static-site-generator
Requires-Python: >=3.11
Requires-Dist: strictcli>=0.7.0
Provides-Extra: og
Requires-Dist: predraw>=0.2.0; extra == 'og'
Provides-Extra: perf
Requires-Dist: brotli>=1.1; extra == 'perf'
Description-Content-Type: text/markdown

<!-- Auto-generated by selfdoc from docs/_README.md — do not edit -->

# selfdocumenting

Code-aware documentation site generator. Builds full static sites from Markdown templates and source code, with directive-based content extraction, auto-generated API/CLI reference pages, theming, search, SEO, and deploy to Cloudflare Pages or GitHub Pages.

Supports Python, Go, and TypeScript/JavaScript. One runtime dependency (strictcli). Pure Python.

## Install

```
pip install selfdocumenting
```

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

```
npm install -g selfdocumenting
```

Requires Python 3.11+.

The npm package is named `selfdocumenting` (npm blocks `selfdoc` due to name similarity). The CLI command remains `selfdoc`.

## Quick start

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

# Auto-generate API and CLI reference pages
selfdoc gen

# Edit docs/ pages -- add directives referencing your code

# Build HTML output
selfdoc build

# Validate directives, coverage, and SEO lint
selfdoc check

# Serve locally with live reload
selfdoc serve
```

## Features

- Attribute-based directive syntax (`:-:`, `:<:`, `:>:`) for embedding code-extracted content
- Auto-generated API reference and CLI docs from source code structure (`selfdoc gen`)
- Sandboxed data generation scripts (`selfdoc gen-data`)
- Theming with dark mode, accent colors, and custom CSS overrides
- Pluggable search (builtin, Fuse.js, or MiniSearch)
- 15+ SEO lint rules, WCAG contrast validation, JSON-LD structured data
- Per-symbol documentation coverage tracking with configurable thresholds
- Build-time Pygments syntax highlighting, code tabs, sortable tables
- CSS/JS/HTML minification, critical CSS inlining, gzip and Brotli pre-compression
- Atom feed, `robots.txt` with AI crawler controls, `llms.txt` / `llms-full.txt`
- Landing page with hero section, tagline, and feature cards
- SSE-based live reload dev server
- Auto-commit of generated files (prefers safegit)

## Directive syntax

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

```
:-: directive-name path="arg"
```

Self-closing directives use `:-:`. Block directives that wrap a body use `:<:` to open, `:>:` to close, with `:=:` and `:::` to delimit sections inside. Directives inside fenced code blocks are ignored.

## Built-in directives

| Directive | Description |
| --- | --- |
| `callout-danger` | Styled danger callout block |
| `callout-important` | Styled important callout block |
| `callout-note` | Styled note callout block |
| `callout-tip` | Styled tip callout block |
| `callout-warning` | Styled warning callout block |
| `code-help` | Extract CLI help/usage text and flag definitions |
| `code-test` | Embed test source code (whole file or specific function) |
| `list-features` | Module summaries from docstring first lines |
| `list-glossary` | Definition list from **Term**: Definition lines |
| `list-modules` | List source modules with file paths and docstring summaries |
| `list-tree` | File/directory tree listing |
| `prose-desc` | Extract module/package docstring as prose text |
| `ref` | Extract module docstring, exported functions, and classes |
| `table-commands` | CLI command summary table from strictcli structure |
| `table-config` | Render a config file (JSON/TOML) as a key-value table |
| `table-config-schema` | Configuration field reference table from schema |
| `table-dep` | Dependencies table from pyproject.toml |
| `table-directives` | Table of all core built-in directives |
| `table-schema` | Extract dataclass/struct fields as a markdown table |
| `var` | Interpolate project metadata value |

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

```markdown
## API Reference

:-: ref path="selfdoc.config"
```

Example -- show a JSON schema as a table:

```markdown
:-: table-schema path="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(attrs, config, body)` function returning a Markdown string.

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

Script interface:

```python
def resolve(attrs: dict, config: dict, body: list) -> str:
    """Return Markdown string to replace the directive block.

    attrs  -- directive attributes as str->str dict (e.g. {"path": "v1.0.0"})
    config -- the full selfdoc.json config dict
    body   -- body lines from the directive block (empty list for one-liners)
    """
    version = attrs.get("path")
    ...
```

Use in templates:

```markdown
:-: changelog path="v1.0.0"
```

Custom directives take priority over built-in names.

## Configuration

`selfdoc.json` at the project root:

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

| Field | Required | Description |
| --- | --- | --- |
| `language` | yes | Programming language of the documented project. |
| `source` | yes | List of source directories or files to extract documentation from. |
| `base_url` | yes | Base URL of the generated site, used for canonical links and SEO. |
| `docs` | no | Directory containing Markdown documentation templates. |
| `output` | no | Output directory for generated HTML files. |
| `theme` | no | Visual theme for the generated site. |
| `repo` | no | GitHub repository URL shown in the site header. |
| `lang` | no | BCP 47 language tag for the site content (e.g. 'en', 'pt-BR'). |
| `description` | no | Short description of the project, used in meta tags and SEO. |
| `branch` | no | Git branch used for source links in the generated site. |
| `search` | no | Search UI mode: icon button, full bar, or hidden. |
| `search_engine` | no | Client-side search engine implementation to use. |
| `code_icons` | no | Style of language icons shown on code blocks. |
| `line_numbers` | no | Show line numbers in code blocks. |
| `run_button` | no | Show a run button on code blocks for supported languages. |
| `page_nav` | no | Show previous/next navigation links between pages. |
| `page_progress` | no | Show a reading progress bar at the top of each page. |
| `glossary` | no | Auto-generate a glossary page from dfn terms. |
| `min_coverage` | no | Minimum documentation coverage percentage required by the check command. |
| `feed_max_entries` | no | Maximum number of entries in the Atom feed, sorted by most recent. |
| `lint_ignore` | no | List of lint rule IDs to suppress (e.g. 'SEO007'). |
| `root_files` | no | List of underscore-prefixed template paths in docs/ for root file generation. |
| `deploy` | no | Deployment configuration for publishing the generated site. |
| `directives` | no | Custom directive mappings from directive name to source file path. |
| `author` | no | Author information for meta tags and structured data. |
| `feedback` | no | Feedback collection configuration (at least one of webhook or ga required). |
| `branding` | no | Landing page branding and call-to-action configuration. |
| `auto_detect` | no | Automatic content detection settings for step guides and API entries. |
| `gen` | no | Configuration for the gen command. |
| `gen_data` | no | Configuration for the gen-data command. |

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

## Commands

| Command | Description |
| --- | --- |
| `init` | Initialize selfdoc in the current project |
| `build` | Build the documentation site |
| `serve` | Serve the documentation site locally |
| `deploy` | Deploy the documentation site |
| `check` | Check documentation coverage and consistency |
| `gen` | Auto-generate documentation pages from project structure |
| `gen-data` | Generate data files by running sandboxed scripts |

## Deploy

### Cloudflare Pages

Requires the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed and authenticated.

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

```bash
selfdoc build && selfdoc deploy
```

### GitHub Pages

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

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

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

## Integration with rlsbl

When [rlsbl](https://github.com/smm-h/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
