CLI documentation adapters
A leaf package can add documentation commands through the shared argparse or
Click adapter. Both adapters dispatch to the same package documentation reader.
They register docs list and docs get; they do not add Dev’s global search,
validation or provider-catalog commands to the leaf.
Usage
These commands run against Dev’s own registered documentation. Replace
scitex-dev with a leaf’s executable when that leaf mounts the adapter.
Use the page names returned by list rather than assuming every package
ships the same pages.
# List available documentation pages
scitex-dev docs list
# Get the page index as structured JSON
scitex-dev docs list --json
# Show the same page index through get
scitex-dev docs get --json
# Read a listed HTML page
scitex-dev docs get cli
# Select the HTML format explicitly
scitex-dev docs get cli --format html
--json on a page listing describes the index, not the content of every page.
Page-specific JSON requires the provider’s JSON build assets. The current
reader tries bundled documentation and then a local Sphinx build. If the
named page is unavailable in both, the adapters report an error and exit 2;
the Python API raises FileNotFoundError. Package introspection remains
available for requests without a page name.
The removed flat flags docs --list, docs --page and docs --tldr
are not the adapter interface.
Integration (argparse)
Replace your-package with the installed distribution name whose
scitex_dev.docs declaration points to its Python package. The executable
name and documentation-provider name can differ.
[project.entry-points."scitex_dev.docs"]
your-package = "your_package"
import argparse
from scitex_dev.cli import register_docs_subcommand
parser = argparse.ArgumentParser(prog="my-tool")
subparsers = parser.add_subparsers(dest="command")
register_docs_subcommand(subparsers, package="your-package")
The caller parses arguments and invokes the selected subcommand’s func
callback. Registering the parser alone does not execute a documentation read.
Integration (Click)
import click
from scitex_dev.cli import docs_click_group
@click.group()
def cli():
pass
cli.add_command(docs_click_group(package="your-package"))
A direct custom mount can use docs_click_group(package="your-package",
name="manual"); its examples use manual. The adapter still exposes only
list and get. Dev separately registers scitex-dev docs search,
docs validate and docs list-providers in its own dispatcher.
Verification and scope
The owning adapters are _core/dispatch/_docs_argparse.py and
_core/dispatch/_docs_click.py. Their real parser, dispatch and
advertised-example controls live under
tests/scitex_dev/_core/dispatch/; Dev-only commands have controls in
tests/scitex_dev/_cli/test__docs_cmds.py. Generated HTML and installed
package resources need separate content and source-binding checks.
Provider discovery or a successful local command does not establish a live
hosted route.
API
- scitex_dev.cli.register_docs_subcommand(subparsers: _SubParsersAction, package: str) ArgumentParser[source]
Register
docswithlistandgetverb subcommands.- Usage::
scitex-stats docs list # List doc pages scitex-stats docs get # Show available pages scitex-stats docs get api # Show specific page