Support use as a Python library

[ewels]

Makes nf-docs usable as an importable Python package, alongside the CLI. The CLI stays the primary interface and its behaviour is unchanged.

Why this was cheap

The core was already side-effect-clean, so most of the work was packaging and documenting what existed rather than restructuring anything:

• Every rich call, sys.exit() and print() already lived in cli.py / tailwind.py. Core modules only use logging.
• Progress was already a decoupled callback protocol, not wired to rich.
• The test suite already imported the package directly.

The real gaps were that nothing was exported, there was no py.typed, and ~150 lines of reusable output policy were trapped inside the generate click command.

The API

import nf_docs

pipeline = nf_docs.extract("./my_pipeline")          # -> Pipeline
markdown = nf_docs.render(pipeline, "markdown")      # -> str
files    = nf_docs.generate("./my_pipeline", output_format="html", output="site/")  # -> list[Path]

generate() always writes files and returns their paths. The CLI's habit of streaming json/yaml to stdout stays in cli.py, since that's a command-line concern rather than an API one.

Changes

• nf_docs/api.py — the three functions above, wrapping PipelineExtractor and the renderers.
• nf_docs/output.py — source and output path policy (format aliases, single-module auto-detection, default filenames and directories), lifted out of cli.py so both entry points share one implementation. cli.py also extracts via api.extract(), so the two stay in sync by construction. It imports nothing from the rest of the package.
• nf_docs/__init__.py — re-exports the facade, models, renderers, progress types and exceptions, with an explicit __all__.
• py.typed — so the existing type hints reach downstream users. Verified present in the built wheel.
• PipelineExtractor(config=...) — library callers get NfDocsConfig() defaults rather than the user's ~/.config/nf-docs/config.yaml, which keeps programmatic use reproducible. The CLI passes load_config() explicitly to preserve its behaviour. The get_config()/reset_config() globals had zero callers left afterwards and were removed.
• docs/python-api.md — new page, added to the nav.

Verification

• 326 tests pass. tests/test_cli.py is unmodified — that's the guardrail for "the CLI didn't move".
• CLI and library output verified byte-identical across all five formats in every output mode: explicit file, explicit directory, default location, stdout, and single-module.
• ruff check, ruff format --check and ty check clean.
• Every code example on the new docs page was executed (this caught a real bug: PipelineCache().clear() needs a Path, not a str).

Not verified: the real Language Server path. The sandbox this was developed in blocks GitHub, so the language-server JAR could not be downloaded and no end-to-end extraction against a live LSP was possible. Everything upstream and downstream of that call was exercised with the LSP stubbed. Worth a manual nf-docs generate against a real pipeline before merging.

Known issue, not addressed here

Most NfDocsConfig fields are documented but never consulted during extraction — include_hidden_params, max_readme_length, strip_readme_badges, exclude_patterns, ignore_input_prefixes and default_format. The behaviours mostly exist but are hardcoded (badge-stripping always runs and never reads strip_readme_badges; hidden is parsed and stored but nothing filters on it; the LSP excludes are hardcoded). Only ignore_config_prefixes takes effect. tests/test_config.py only round-trips the values, so the suite doesn't catch it.

The new docs page documents just ignore_config_prefixes so the library doesn't advertise inert options. Wiring up the rest is a separate change.

🤖 Generated with Claude Code

https://claude.ai/code/session_013qwciLzAxtZMwu3uWnA24H

---

Generated by Claude Code