smalldocs 0.1.0__tar.gz

smalldocs-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,32 @@
+name: docs
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run smalldocs render docs --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

smalldocs-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+_site/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+docs/api/
+docs/_symbols.json

smalldocs-0.1.0/CLAUDE.md

@@ -0,0 +1,88 @@
+# smalldocs
+
+smalldocs builds a Quarto-like website from a `_quarto.yml` project, in pure Python, and is published on
+PyPI as `smalldocs`. It exists so that Rahul's projects (babykev, smallwikiapp, nbinlineai, ProblemSolving,
+the timewalk class kits) can build their docs sites without Quarto, which is 600 MB of Pandoc, Deno, Sass
+and Typst. It makes websites only: no PDF, Word, slides or books, and it runs no code.
+
+The user documentation is the site in `docs/`, built by smalldocs itself. Keep it true when the behaviour
+changes. The README is a short front page.
+
+## Rules the tool must keep
+
+- **A project that builds with Quarto builds with smalldocs, with the same pages, the same anchors and the
+  same links.** Heading ids follow Pandoc's algorithm (`markdown.pandoc_id`); links to `.qmd`/`.md`/`.ipynb`
+  become `.html`; links from `/` start at the root. Check a change against real sites (below).
+- **Read `_quarto.yml` unchanged.** smalldocs' own settings live under `smalldocs:`, which Quarto ignores. A
+  key smalldocs does not read is a warning, never silent.
+- **Any Bootswatch theme, with no Sass.** `assets/smalldocs.css` uses only Bootstrap's `--bs-*` variables
+  and its own `--sd-*` ones. Never hard-code a colour that a theme should set (the Quarto highlight colours
+  and the inline-code purple are the exceptions, with dark variants under `html.quarto-dark`).
+- **The output folder is emptied at each build**, so `Site.check_output` refuses an output folder that is
+  the project or above it, holds `.git`, or is not empty and has no `site_libs`. The API build deletes only
+  pages listed in its manifest, `api/.smalldocs-api`, and `api.out` must be inside the site. Keep these
+  guards; each has a test.
+- **Never publish a source.** A link to a page that is not built is reported, and its `.qmd` is never
+  copied. `resources` and `render` take one glob or a list (`config.as_list`); globs use `config.glob_match`
+  (as Quarto: with a `/`, `*` stays in one folder; with no `/`, the glob matches at any depth).
+- **`publish` never touches the working tree or the current branch.** It works in a temporary worktree,
+  removes it in `finally`, deletes only a branch it made (a uuid name), skips hooks, and refuses to
+  publish onto the current branch, the remote's default branch, `main` or `master`.
+- **`smalldocs api` must import only fastcore and PyYAML**, because it runs in the documented project's
+  environment. Keep the imports in `cli.py` lazy.
+- **The API pages are byte-for-byte what babykev's `apidocs.py` made.** `api.module_markdown` and `api.page`
+  are ported from `babykev/src/babykev/docs.py` and `babykev/docs/apidocs.py`.
+
+## Layout
+
+| File | What it is |
+|---|---|
+| `src/smalldocs/config.py` | `_quarto.yml`: load, merge (`merge`, `dir_metadata`), the known keys, `ConfigError`, `BuildError` |
+| `src/smalldocs/markdown.py` | markdown-it-py with mdit-py-plugins, and Pandoc's rules: heading attributes and ids, fenced divs, callouts, tabsets, figures, sections, typography, code, maths |
+| `src/smalldocs/highlight.py` | Pygments tokens to Pandoc's classes (`kw`, `st`, `co`, ...) |
+| `src/smalldocs/notebook.py` | `.ipynb` to Markdown with raw HTML outputs; nothing runs |
+| `src/smalldocs/shortcodes.py` | `include`, `meta`, `var`, `env`, `pagebreak` |
+| `src/smalldocs/site.py` | `Site`: discovery, pages, link rewriting (`resolve`), scripts, assets, resources, search.json, sitemap |
+| `src/smalldocs/layout.py` | `SiteNav` (sidebars, navbar, order, breadcrumbs) and `Layout` (the page, in Quarto's markup, with `fastcore.xml`) |
+| `src/smalldocs/listing.py` | Listings (default, grid, table), categories, RSS |
+| `src/smalldocs/api.py` | The API reference: inventory, Markdown, pages, `_symbols.json`, `check` |
+| `src/smalldocs/serve.py`, `publish.py`, `check.py`, `cli.py` | The commands |
+| `src/smalldocs/assets/` | `smalldocs.css`, `smalldocs.js`, and `vendor/` (Bootswatch 5.3.8, Bootstrap 5.3.8, Bootstrap Icons 1.11.3, Fuse.js 7.0.0). Vendored: do not edit |
+| `tests/test_smalldocs.py` | One test per feature |
+| `docs/` | smalldocs' own site; it uses every feature, and its Reference is made by `smalldocs.api` from this package |
+
+## Commands
+
+```
+just test            # pytest; extra arguments go to pytest
+just lint            # ruff
+just render DIR      # build a site
+just docs            # preview smalldocs' own site with reload
+just build           # the wheel and sdist into dist/
+```
+
+## Checking a change
+
+1. `just test` and `just lint`, as separate commands; read each result.
+2. `uv run smalldocs api check --dir docs`: every function typed and documented.
+3. For anything in `layout.py`, `markdown.py` or `assets/`: build `docs/` and drive it in headless Chrome
+   (Playwright, `channel="chrome"`): tabs, callouts, search, the dark toggle, listings, a phone width.
+4. Against real sites: copy a site into the scratchpad (never build in place: ProblemSolving's
+   `output-dir` is `../docs`, a folder of its repository), render it with Quarto and with smalldocs, and
+   compare the pages, the ids and the links. babykev needs its own Python for the API; run smalldocs
+   with `PYTHONPATH` set to `src` and to this project's site-packages.
+5. An adversarial review by an Opus subagent before each commit.
+
+## Conventions
+
+- Python 3.11+, ruff with line length 150. Dependencies: fastcore, markdown-it-py, mdit-py-plugins,
+  PyYAML, Pygments. Nothing else at run time.
+- Type and document every function in the docments style: one comment per parameter, one on the return,
+  a one-line docstring.
+- Plain, short sentences in docs, docstrings and messages.
+- Ask Rahul before every commit. End each commit message with the line `Coded using Claude`.
+
+## Releasing
+
+Raise `version` in `pyproject.toml` and `__version__` in `src/smalldocs/__init__.py`, run the checks,
+`just build`, then `uv publish` (the token is in `~/.pypirc`; pass it with `--token`). Tag `vX.Y.Z`.

smalldocs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Dave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smalldocs-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: smalldocs
+Version: 0.1.0
+Summary: Quarto-like websites from a _quarto.yml project, in pure Python: pages, API reference and listings
+Project-URL: Homepage, https://github.com/rahuldave/smalldocs
+Author-email: Rahul Dave <rahuldave@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: src/smalldocs/assets/vendor/bootstrap-icons/LICENSE
+License-File: src/smalldocs/assets/vendor/bootstrap/LICENSE
+License-File: src/smalldocs/assets/vendor/bootswatch/LICENSE
+License-File: src/smalldocs/assets/vendor/fuse/LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: fastcore>=1.8
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pygments>=2.17
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# smalldocs
+
+smalldocs builds a website from a [Quarto](https://quarto.org) project, in pure Python. It reads the same
+`_quarto.yml` and the same Markdown, and writes the same kind of site into `_site`: pages with a navbar, a
+sidebar and a table of contents, notebooks with their saved outputs, reference pages made from your code,
+and listings of posts with categories and a feed. The site takes any [Bootswatch](https://bootswatch.com)
+theme, in light and dark.
+
+It makes websites only: no PDF, Word, slides or books, and it runs no code. In return it is one package
+from PyPI, with no Pandoc, Deno, Sass or TeX.
+
+```bash
+pip install smalldocs
+
+smalldocs render docs              # build docs/_site
+smalldocs preview docs             # serve it at http://127.0.0.1:4200, rebuild and reload on each change
+smalldocs check docs               # what smalldocs ignores, broken links, Markdown only Pandoc reads
+smalldocs api build --dir docs     # the API reference, from docstrings, types and docments
+smalldocs publish gh-pages docs    # push the site to the gh-pages branch
+```
+
+The documentation is in [`docs/`](docs/), built with smalldocs.
+
+## What it reads
+
+- `_quarto.yml`, `_metadata.yml` and front matter, merged as Quarto merges them: `project`
+  (`output-dir`, `render`, `resources`, `pre-render`, `post-render`), `website` (navbar, sidebar, page
+  navigation, footer, search, site URL, repository links) and `format.html` (theme, CSS, table of contents,
+  numbered sections, includes).
+- Markdown: CommonMark, tables, footnotes, definition lists, task lists, `{#id .class}` attributes,
+  fenced divs, callouts, tabsets, `$` maths (KaTeX), mermaid, raw HTML, and the shortcodes `include`,
+  `meta`, `var` and `env`. Heading ids follow Pandoc's rules, so links written for Quarto keep working.
+- Notebooks, with the outputs they were saved with, and Quarto's `#|` cell options.
+- Listings: `default`, `grid` and `table`, with sorting, filtering, categories, pages and RSS.
+
+## Licence
+
+MIT. smalldocs ships Bootstrap, Bootswatch and Bootstrap Icons (MIT) and Fuse.js (Apache-2.0), each with
+its licence in `src/smalldocs/assets/vendor/`.

smalldocs-0.1.0/PLAN.md

@@ -0,0 +1,175 @@
+# smalldocs: a plan
+
+A small, pure-Python tool that builds a Quarto-like website from a `_quarto.yml` project: regular pages,
+API reference pages, and listing (blog/collection) pages, into `_site`. No PDF, Word, slides, books,
+code execution, Lua, Sass or Pandoc.
+
+## 1. What we use Quarto for today (surveyed 2026-10-10)
+
+18 `_quarto.yml` sites under `~/Projects` (babykev and its copies, smallwikiapp, nbinlineai and its
+copies, ProblemSolving, smallwikiapp-walk, babykev-class prototype). timewalk-test has none: its tags
+hold no `docs/`. All are `type: website` except `playing_with_quarto` (a book, with pdf and docx).
+
+Config keys in use, and nothing else:
+
+| Area | Keys |
+|---|---|
+| project | `type: website`, `output-dir`, `pre-render`, `render` (globs), `resources` (globs) |
+| website | `title`, `description`, `site-url`, `repo-url`, `navbar.left` (text/href), `sidebar` (`style: docked`, `search`, `contents` with files, globs like `api/*`, `section:`, `text`/`href`), `page-navigation`, `search` |
+| format.html | `theme: cosmo` (every site), `css`, `toc`, `toc-depth`, `code-copy`, `from: markdown-tex_math_dollars-smart` |
+| filters | `linkify.lua` only: a backticked name becomes a link to its API entry, from `_symbols.json` |
+
+Markdown in the 71 pages: pipe tables (43 pages), images, `{#id}` on headings, `{.source-link}` on
+links, inline `$` (dollars, not maths). No callouts, tabsets, listings, shortcodes, cross-refs, footnotes
+or executed code. One notebook (`babykev/docs/guide/01_mask.ipynb`), rendered from stored outputs.
+
+The API pages come from a per-project `docs/apidocs.py` (86 lines) over a per-project `docs.py`
+(babykev: 451 lines; fastcore `docments`, dataclasses, pydantic). The copies have drifted
+(smallwikiapp's has `check` and `module`; babykev's does not).
+
+Quarto 1.8.26 is 638 MB: Deno, Pandoc, dart-sass, esbuild and Typst.
+
+## 2. Feasibility: yes
+
+- **Themes without Sass.** Quarto compiles Bootswatch Sass with its own layer. We do not need to:
+  Bootswatch 5.3.8 ships each of its 25 themes as a plain `bootstrap.min.css` (about 30 KB gzipped), and
+  Bootstrap 5.3 exposes the theme as CSS variables (`--bs-primary`, `--bs-body-bg`, `--bs-border-color`,
+  `--bs-secondary-bg`, `--bs-link-color`, `--bs-font-sans-serif`, ...). One hand-written `smalldocs.css`
+  that uses only these variables, plus Bootstrap's own classes (`navbar`, `card`, `nav-tabs`, `table`,
+  `alert`), looks right under every theme. All 25 vendored add about 750 KB to the wheel; a build copies
+  only the chosen one into `_site/site_libs/`.
+- **Markdown.** markdown-it-py (the parser behind MyST) with mdit-py-plugins covers front matter,
+  tables, footnotes, definition lists, `$` maths, task lists and inline `{.class}` attributes. We add
+  small rules for what Pandoc has and it lacks: `{#id .class}` after a heading, fenced divs
+  `::: {.class}`, raw `{=html}` blocks, and Pandoc's heading-id algorithm, so anchors stay the same.
+- **HTML.** We copy the shape of Quarto's markup (its class and id names: `#quarto-header`,
+  `#quarto-sidebar`, `#TOC`, `.quarto-title-block`, `.quarto-grid-item`, `callout-*`, `panel-tabset`),
+  not its files, and write it with `fastcore.xml` (FT components), so templating adds no dependency.
+- **Notebooks.** `.ipynb` is JSON: markdown cells, code cells, and stored outputs (stream, text/plain,
+  text/html, image/png, image/svg+xml, error with ANSI stripped), with `#| echo: false` and
+  `#| output: false`. No kernel, as Quarto by default.
+- **API docs.** Generalise babykev's `docs.py` and `apidocs.py` into `smalldocs.api`, and build
+  `linkify.lua` in. This removes the drifting copies.
+
+Dependencies: `fastcore`, `markdown-it-py`, `mdit-py-plugins`, `PyYAML`, `Pygments`. All pure Python.
+Vendored: Bootswatch and Bootstrap (MIT), Fuse.js (Apache-2.0) for search.
+
+Estimate: 3,000 to 4,000 lines of Python, about 600 of CSS and JS.
+
+## 3. Risks, and what we do about them
+
+| Risk | Answer |
+|---|---|
+| markdown-it is not Pandoc: grid tables, citations `[@key]`, raw LaTeX, `{.class}` on spans | Out of scope; `smalldocs check` names each one with file and line. None of our sites uses them |
+| Anchors change and links break | Pandoc's id algorithm, tested against Quarto's output; a link checker in `render` |
+| `.qmd` links | Rewrite `.qmd`/`.md`/`.ipynb` to `.html` and root `/` links to relative ones, as Quarto does (`_symbols.json` targets are `/api/api.qmd#Noul`) |
+| Looks almost like Quarto, not exactly | Screenshot comparisons against Quarto under cosmo, flatly, darkly and sketchy |
+| `theme: [cosmo, custom.scss]` | Refused with a message: use `css:` and `--bs-*` variables. No site of ours uses `.scss` |
+| Lua filters | Ignored with a warning; the only one we use (linkify) is built in. Later: Python filters |
+| `{python}` cells in `.qmd` | Shown as code, not run, with a warning |
+
+## 4. What smalldocs does
+
+**Commands**
+
+```
+smalldocs render [DIR]            build DIR (default .) into its output-dir, default _site
+smalldocs preview [DIR] [--port]  render, serve, rebuild on change, reload the browser
+smalldocs check [DIR]             config keys we ignore, Pandoc-only syntax, broken links
+smalldocs api build|check|module NAME   the reference pages; the gaps in the docments; one module as Markdown
+smalldocs publish gh-pages [DIR]  push the output-dir to the gh-pages branch (as quarto publish gh-pages)
+```
+
+**Config.** Read `_quarto.yml` unchanged, so one site builds with either tool. Our own settings go
+under a `smalldocs:` key, which Quarto ignores:
+
+```yaml
+smalldocs:
+  api:
+    packages: [babykev]          # importable packages to document
+    out: api                     # pages go to docs/api/
+    source: https://github.com/rahuldave/babykev/blob/main
+    linkify: true                # `render` in prose links to its entry
+```
+
+Unknown keys get a warning that names them; `--strict` makes it an error.
+
+**Supported, by area**
+
+- project: `type: website`, `output-dir`, `render`, `resources`, `pre-render`, `post-render` (run with
+  Quarto's `QUARTO_PROJECT_*` environment variables).
+- website: `title`, `description`, `site-url` (sitemap.xml), `repo-url` (link and repo actions),
+  `favicon`, `navbar` (left/right, menus, `search`), `sidebar` (docked/floating, files, globs, sections,
+  `auto`), `page-navigation`, `page-footer`, `search` (search.json and a Fuse.js box), `open-graph` (basic).
+- format.html: `theme` (any Bootswatch name, or `light:`/`dark:` with a toggle), `css`, `toc`,
+  `toc-depth`, `toc-title`, `number-sections`, `code-copy`, `highlight-style` (Pygments),
+  `from: ...-tex_math_dollars-smart`, `page-layout` (article, full), `anchor-sections`.
+- page front matter: `title`, `subtitle`, `description`, `author`, `date`, `categories`, `image`,
+  `draft`, `toc`, `listing`, `page-layout`, `search: false`.
+- Markdown: CommonMark, pipe tables, footnotes, definition lists, task lists, `{#id .class key=val}`,
+  fenced divs, callouts (note, tip, warning, important, caution; collapse; title), `panel-tabset`,
+  raw HTML, `$`/`$$` maths with KaTeX, mermaid blocks (mermaid.js from a CDN).
+- Listings (`listing:` in front matter): `contents` (globs), `type: default|grid|table`, `sort`,
+  `fields`, `categories` (with filter), `sort-ui`, `filter-ui`, `page-size`, `max-items`,
+  `grid-columns`, `image-height`, `feed: true` (RSS). Item data from each page's front matter; when it
+  is missing, the first paragraph for the description and the first image for the picture. Several
+  listings per page, by `id`.
+- API: the generic `smalldocs.api` from babykev's `docs.py`. Modules, classes, methods, functions;
+  signatures with types; docment tables; dataclass fields; pydantic fields (detected, not imported);
+  TypedDict keys with comments; a source link per entry; the `check` of docments; and the name index
+  that the built-in linkify uses.
+
+## 5. Layout of the repository
+
+```
+smalldocs/
+  pyproject.toml   justfile   ruff.toml   CLAUDE.md   README.md
+  src/smalldocs/
+    config.py      # _quarto.yml: load, defaults, unknown keys, globs
+    markdown.py    # markdown-it setup and the Pandoc-like rules (ids, divs, callouts, tabsets, raw)
+    notebook.py    # .ipynb to the same tokens
+    pages.py       # discovery, front matter, link rewriting, the page model
+    layout.py      # fastcore.xml: navbar, sidebar, title block, TOC, page nav, footer
+    listing.py     # listings and RSS
+    search.py      # search.json, sitemap.xml
+    api.py         # the API reference (from babykev docs.py and apidocs.py)
+    serve.py       # preview: http.server, watch, reload
+    publish.py     # gh-pages
+    cli.py         # the commands, with fastcore.script
+    assets/        # smalldocs.css, smalldocs.js, vendor/{bootswatch/*, bootstrap, fuse, katex?}
+  tests/           # one test per feature, and a kitchen-sink site
+  docs/            # smalldocs' own site, built by smalldocs: it uses every feature
+```
+
+## 6. Phases
+
+Each phase ends with its tests green and an Opus adversarial review, as in timewalk.
+
+1. **Skeleton.** pyproject (hatchling, uv), justfile, ruff, CLAUDE.md, vendored assets with licences.
+2. **Core render.** Config, discovery, the Markdown pipeline, link rewriting, navbar, sidebar, TOC,
+   title block, themes, `css`, `resources`, `pre-render`. Test: babykev/docs, smallwikiapp-walk/site,
+   nbinlineai/docs and ProblemSolving/site build with no Quarto, and every link resolves.
+3. **Pages in full.** Notebooks, Pygments highlighting, code-copy, callouts, tabsets, maths, mermaid,
+   page navigation, footer, light/dark.
+4. **API.** `smalldocs.api` and the built-in linkify. Test: babykev's reference pages and
+   `_symbols.json` match what `apidocs.py` makes today.
+5. **Listings and search.** Default, grid and table; categories; sorting; pages; RSS; search.json and
+   the search box; sitemap.
+6. **Preview and publish.** `smalldocs preview` with reload; `publish gh-pages`.
+7. **Compare with Quarto.** Render each surveyed site with both into the scratchpad. Compare pages,
+   anchors and links mechanically, and screenshots by eye under four themes. Write smalldocs' own docs.
+8. **Release.** GitHub repo `rahuldave/smalldocs`, PyPI via trusted publishing from a GitHub Action,
+   `v0.1.0`.
+
+Only after that, and when you say so: move babykev, timewalk-test and the kits from Quarto to
+smalldocs.
+
+## 7. Decisions for you
+
+1. **Name.** `smalldoc` is taken on PyPI (a 2012 SmallTalk-style API documenter by sebastien).
+   `smalldocs` is free. I recommend it.
+2. **Templates in `fastcore.xml`, not Jinja2.** One dependency fewer, and in Python. The cost: a user
+   cannot override a template file; they override with CSS, or with a Python hook later.
+3. **Vendor all 25 Bootswatch themes** in the wheel (about 750 KB), so that a build works offline. The
+   other choice is links to a CDN.
+4. **PyPI.** Publishing needs a trusted publisher set up on your PyPI account for the GitHub repository.

smalldocs-0.1.0/README.md

@@ -0,0 +1,39 @@
+# smalldocs
+
+smalldocs builds a website from a [Quarto](https://quarto.org) project, in pure Python. It reads the same
+`_quarto.yml` and the same Markdown, and writes the same kind of site into `_site`: pages with a navbar, a
+sidebar and a table of contents, notebooks with their saved outputs, reference pages made from your code,
+and listings of posts with categories and a feed. The site takes any [Bootswatch](https://bootswatch.com)
+theme, in light and dark.
+
+It makes websites only: no PDF, Word, slides or books, and it runs no code. In return it is one package
+from PyPI, with no Pandoc, Deno, Sass or TeX.
+
+```bash
+pip install smalldocs
+
+smalldocs render docs              # build docs/_site
+smalldocs preview docs             # serve it at http://127.0.0.1:4200, rebuild and reload on each change
+smalldocs check docs               # what smalldocs ignores, broken links, Markdown only Pandoc reads
+smalldocs api build --dir docs     # the API reference, from docstrings, types and docments
+smalldocs publish gh-pages docs    # push the site to the gh-pages branch
+```
+
+The documentation is in [`docs/`](docs/), built with smalldocs.
+
+## What it reads
+
+- `_quarto.yml`, `_metadata.yml` and front matter, merged as Quarto merges them: `project`
+  (`output-dir`, `render`, `resources`, `pre-render`, `post-render`), `website` (navbar, sidebar, page
+  navigation, footer, search, site URL, repository links) and `format.html` (theme, CSS, table of contents,
+  numbered sections, includes).
+- Markdown: CommonMark, tables, footnotes, definition lists, task lists, `{#id .class}` attributes,
+  fenced divs, callouts, tabsets, `$` maths (KaTeX), mermaid, raw HTML, and the shortcodes `include`,
+  `meta`, `var` and `env`. Heading ids follow Pandoc's rules, so links written for Quarto keep working.
+- Notebooks, with the outputs they were saved with, and Quarto's `#|` cell options.
+- Listings: `default`, `grid` and `table`, with sorting, filtering, categories, pages and RSS.
+
+## Licence
+
+MIT. smalldocs ships Bootstrap, Bootswatch and Bootstrap Icons (MIT) and Fuse.js (Apache-2.0), each with
+its licence in `src/smalldocs/assets/vendor/`.

smalldocs-0.1.0/docs/_quarto.yml

@@ -0,0 +1,48 @@
+project:
+  type: website
+  output-dir: _site
+
+website:
+  title: smalldocs
+  description: Quarto-like websites from a _quarto.yml project, in pure Python
+  site-url: https://rahuldave.com/smalldocs/
+  repo-url: https://github.com/rahuldave/smalldocs
+  repo-actions: [source, issue]
+  page-navigation: true
+  navbar:
+    left:
+      - href: index.qmd
+        text: Home
+      - href: guide/get-started.qmd
+        text: Guide
+      - href: api/site.qmd
+        text: Reference
+      - href: news/index.qmd
+        text: News
+    tools:
+      - icon: github
+        href: https://github.com/rahuldave/smalldocs
+  sidebar:
+    style: floating
+    contents:
+      - section: Guide
+        contents: guide/*
+      - section: Reference
+        contents: api/*
+  page-footer:
+    left: "smalldocs is MIT-licensed."
+    right: "Built with [smalldocs](https://github.com/rahuldave/smalldocs)."
+
+format:
+  html:
+    theme:
+      light: cosmo
+      dark: darkly
+    toc: true
+    code-copy: true
+
+smalldocs:
+  api:
+    packages: [smalldocs]
+    root: ..
+    source: https://github.com/rahuldave/smalldocs/blob/main

smalldocs-0.1.0/docs/guide/api.qmd

@@ -0,0 +1,81 @@
+---
+title: The API reference
+description: Reference pages made from your code, and names in backticks that link to them.
+order: 5
+---
+
+smalldocs writes a reference page for each module of your package. It reads what the code already
+says: the types from the annotations, the description of each parameter from the comment beside it,
+and the summary from the docstring. Nothing is written twice. The [Reference](../api/site.qmd) of this
+site is made this way, from smalldocs' own code.
+
+## Write the code
+
+Put one parameter on each line, with its comment beside it, and the return's comment after the
+colon of the `def` line. [fastcore](https://fastcore.fast.ai) calls these comments *docments*.
+
+```python
+def add(
+    a: int,  # The first number
+    b: int = 2,  # The second number
+) -> int:  # Their sum
+    "Add two numbers."
+    return a + b
+```
+
+A dataclass shows its constructor, with the comment beside each field. A pydantic model shows its
+fields, with their descriptions. A `TypedDict` shows its keys, with the comment beside each.
+
+## Turn it on
+
+```yaml
+smalldocs:
+  api:
+    packages: [mypkg]                  # the importable packages to document
+    out: api                           # the folder of pages, inside the site; `api` by default
+    root: ..                           # the repository's root, from the site's folder; `..`, or `.` when the site's folder holds pyproject.toml
+    source: https://github.com/me/mypkg/blob/main   # each entry links to its line here
+    check: ["*.py", "tests/**/*.py"]   # more files that `smalldocs api check` holds to the convention
+```
+
+Then every build writes `api/<module>.qmd`, one page for each public module, and `_symbols.json`,
+the index of names. `out` must be a folder inside the site. smalldocs notes the pages it writes in
+`api/.smalldocs-api`, and deletes a page only when an earlier build wrote it and this one did not, so a
+page of your own in that folder, such as `api/index.qmd`, is safe. List the pages in the sidebar with
+a glob:
+
+```yaml
+website:
+  sidebar:
+    contents:
+      - section: Reference
+        contents: api/*
+```
+
+smalldocs imports your package, so install it in the same environment as the package. If it cannot
+import the package, it also looks in the repository's root and in its `src` folder.
+
+## Links from the prose
+
+With the API on, a name in backticks that the reference documents becomes a link to its entry,
+anywhere on the site: `Site`, `inventory`, `smalldocs.markdown.render`. A name in a link stays as it is, and a name
+that the reference does not know stays as code.
+
+## At the terminal
+
+```bash
+smalldocs api build --dir docs        # write the pages and the index
+smalldocs api module site --dir docs  # print one module as plain Markdown, for people and agents
+smalldocs api list --dir docs         # every module, class, method and function, one line each
+smalldocs api check --dir docs        # what is typed and documented, and every gap; exit 1 if any
+```
+
+`check` reports each function without a docstring, each parameter without a type or a docment, and
+each return without one. Run it in your tests or before each commit.
+
+## Coming from apidocs.py
+
+A project that made its reference with its own `apidocs.py` and `linkify.lua` keeps working: smalldocs
+runs the `pre-render` script, and linkify is on when `filters` lists `linkify.lua`. To move to
+`smalldocs.api`, add the section above, then drop `pre-render`, `apidocs.py`, the filter and
+`linkify.lua`. The pages that it writes are the same, byte for byte.

smalldocs-0.1.0/docs/guide/commands.qmd

@@ -0,0 +1,66 @@
+---
+title: The commands
+description: Every command of smalldocs and its options.
+order: 9
+---
+
+Each command takes the project's folder, the one with `_quarto.yml`. It is the folder you are in
+when you give none.
+
+## render
+
+```bash
+smalldocs render [DIR] [--quiet] [--strict]
+```
+
+Build the site. `--quiet` prints only warnings and errors. `--strict` exits with 1 when there is a
+warning, such as a broken link or a key that smalldocs ignores.
+
+## preview
+
+```bash
+smalldocs preview [DIR] [--port 4200] [--host 127.0.0.1] [--no-browser]
+```
+
+Build the site, serve it, and open a browser. On each change to a file of the project, build it
+again; the browser reloads. A failed build prints its error and keeps the last good site. It
+listens on this machine only, unless you give `--host`.
+
+## check
+
+```bash
+smalldocs check [DIR]
+```
+
+Build the site into a scratch folder, and list what to look at before you move from Quarto: keys
+that smalldocs ignores, broken links, and Markdown that only Pandoc reads. Exit with 1 if there is
+anything.
+
+## api
+
+```bash
+smalldocs api build|check|list [--dir DIR]
+smalldocs api module NAME [--dir DIR]
+```
+
+Make the reference pages, check the docments, list the symbols, or print one module as Markdown. See
+[The API reference](api.qmd).
+
+## publish
+
+```bash
+smalldocs publish gh-pages [DIR] [--branch gh-pages] [--remote origin] [--no-render] [-m MESSAGE]
+```
+
+Build the site and push it to the branch, through a temporary worktree. Your working tree and your
+branch do not change, and your git hooks do not run on the site's commit. It refuses to publish onto
+your current branch, the remote's default branch, `main` or `master`, which hold your sources.
+`--no-render` publishes the output folder as it is.
+
+## Exit codes
+
+| Code | Means |
+|---|---|
+| 0 | Done |
+| 1 | Done, with something to fix: `--strict` with warnings, or `check` and `api check` with findings |
+| 2 | Stopped: no `_quarto.yml`, a bad option, a failed script, or a port in use |