--doc with TAB completion for easy access to docs

Author: per2jensen

v2/Changelog.md

@@ -7,6 +7,10 @@ For a high-level summary see [CHANGELOG.md](../CHANGELOG.md) in the repo root.
 
 ### Added
 
+- **`--doc` / `--doc-pretty` CLI options** (`dar-backup`) — print any installed documentation file by name and exit.  Tab completion lists available doc names from the installed package (`dar-backup --doc <TAB>`).  Plain and rich-rendered variants mirror the existing `--readme` / `--readme-pretty` pattern.
+
+- **`scripts/copy_docs.sh`** — shared script called by `build.sh`, `release.sh`, and test fixtures to copy user-facing `doc/*.md` files into `src/dar_backup/` for wheel inclusion.  Internal files (`todo.md`, `dev.md`, `dar_manager_w_dst_bug_report.md`, `NFS server notes.md`) are excluded.  Tests in `tests/test_readme_changelog.py` verify the correct set of files is present and absent after the script runs.
+
 - **Structured large-scale test results** (`doc/test-report/large-scale-results.jsonl`) — `large_scale_test.sh` now appends one JSONL record per run containing datestamp, git commit, tool versions (dar-backup, dar, par2, python), OS, kernel, elapsed times, backup sizes, per-tool peak memory, failure count, and pass/fail status.  The file is written to `${RESULTS_DIR}` and mirrored to `doc/test-report/` in the repo so runs are git-tracked.  Four historical runs (2026-06-09 through 2026-06-20) are backfilled.
 
 - **`show_large_scale_results.py`** (`scripts/`) — parses `large-scale-results.jsonl` and prints a fixed-width ASCII table sorted newest-first.  Defaults to `doc/test-report/large-scale-results.jsonl`; accepts an optional path argument.

v2/build.sh

@@ -6,9 +6,9 @@ set -euo pipefail
 if [ ! -d venv ]; then
     python3 -m venv venv
 fi
+# shellcheck disable=SC1091
 source venv/bin/activate
 
-PYTHON="$(which python3)"
 PIP="$(which pip)"
 
 echo "🔧 Installing project in editable mode in venv: $VIRTUAL_ENV"
@@ -19,6 +19,10 @@ echo "✅ Project installed in editable mode."
 echo "🧹 Cleaning old build artifacts..."
 rm -rf dist/* 2>/dev/null || true
 
+echo "📄 Copying docs into package for wheel inclusion..."
+trap 'rm -f src/dar_backup/README.md src/dar_backup/Changelog.md; rm -f src/dar_backup/doc/*.md 2>/dev/null; rmdir src/dar_backup/doc 2>/dev/null || true' EXIT
+bash scripts/copy_docs.sh
+
 echo "📦 Building installable packages (sdist + wheel)..."
 hatch build --clean
 echo "✅ Packages written to dist/:"

v2/doc/cli-reference.md

@@ -53,6 +53,8 @@ Available options:
 --readme-pretty                      Print README.md with Markdown styling and exit
 --changelog                          Print Changelog and exit
 --changelog-pretty                   Print Changelog with Markdown styling and exit
+--doc <name>                         Print a documentation file by name and exit (tab completion lists available docs)
+--doc-pretty <name>                  Print a documentation file with Markdown styling and exit
 -v, --version                         Show version and license information.
 ```
 

v2/doc/shell-completion.md

@@ -20,6 +20,15 @@ The `dar-backup`, `manager`, and `cleanup` scripts support dynamic tab-completio
 
   manager:  --list-archive-contents, --add-specific-archive (autocomplete those **not** in the catalog database), --remove-specific-archive
 
+- `--doc` and `--doc-pretty` complete from the installed documentation files:
+
+  ```bash
+  dar-backup --doc <TAB>
+  # ⤷ Suggests: cli-reference, config-reference, dar-tips, getting-started, ...
+  dar-backup --doc-pretty rest<TAB>
+  # ⤷ Suggests: restoring
+  ```
+
 - Supports paths like ~ and $HOME correctly
 
 ## Use it

v2/release.sh

@@ -297,27 +297,13 @@ TEMP_CHANGELOG="src/dar_backup/Changelog.md"
 trap 'rm -f "$TEMP_README" "$TEMP_CHANGELOG"; rm -f src/dar_backup/doc/*; rmdir src/dar_backup/doc' EXIT
 
 if $DRY_RUN; then
-    dryrun "copy README.md and Changelog.md into src/dar_backup/ for wheel inclusion"
     dryrun "refresh v2/README.md from root README.md for PyPI description"
-    dryrun "copy doc/*.md into src/dar_backup/doc/ for wheel inclusion"
+    dryrun "copy docs into src/dar_backup/ for wheel inclusion (scripts/copy_docs.sh)"
 else
     cp ../README.md README.md  ||
         { red "❌ Error: Failed to refresh README.md from root"; exit 1; }
 
-    cp ../README.md "$TEMP_README"  ||
-        { red "❌ Error: Failed to copy README.md to $TEMP_README"; exit 1; }
-
-    cp Changelog.md "$TEMP_CHANGELOG"  ||
-        { red "❌ Error: Failed to copy Changelog.md to $TEMP_CHANGELOG"; exit 1; }
-
-    mkdir -p src/dar_backup/doc
-
-    find doc/ -maxdepth 1 -name "*.md" \
-    ! -name "todo.md" \
-    ! -name "dev.md" \
-    ! -name "dar_manager_w_dst_bug_report.md" \
-    ! -name "NFS server notes.md" \
-    -exec cp {} src/dar_backup/doc/ \;
+    scripts/copy_docs.sh || { red "❌ Error: copy_docs.sh failed"; exit 1; }
 fi
 
 

v2/scripts/copy_docs.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# copy_docs.sh — copy user-facing docs into src/dar_backup/ for wheel inclusion
+#
+# Called by build.sh, release.sh, and test fixtures so that README.md,
+# Changelog.md, and doc/*.md are present in installed packages and the
+# --readme / --changelog / --readme-pretty / --changelog-pretty CLI options
+# can find them via _resolve_doc_path().
+#
+# Must be run from the v2/ directory.
+# Cleanup of the copied files is the caller's responsibility.
+
+set -euo pipefail
+
+[[ -f "pyproject.toml" && -d "src/dar_backup" ]] \
+    || { echo "ERROR: must be run from the v2/ directory" >&2; exit 1; }
+
+cp ../README.md   src/dar_backup/README.md
+cp Changelog.md   src/dar_backup/Changelog.md
+
+mkdir -p src/dar_backup/doc
+find doc/ -maxdepth 1 -name "*.md" \
+    ! -name "todo.md" \
+    ! -name "dev.md" \
+    ! -name "dar_manager_w_dst_bug_report.md" \
+    ! -name "NFS server notes.md" \
+    -exec cp {} src/dar_backup/doc/ \;
+
+echo "docs copied to src/dar_backup/"

v2/src/dar_backup/__about__.py

@@ -1,4 +1,4 @@
-__version__ = "1.1.10.dev21"
+__version__ = "1.1.10.dev22"
 
 __author__ = "Per Jensen"
 

v2/src/dar_backup/dar_backup.py

@@ -1928,6 +1928,61 @@ def print_readme(path: str = None, pretty: bool = True):
     resolved_path = _resolve_doc_path(path, "README.md")
     print_markdown(str(resolved_path), pretty=pretty)
 
+
+def _list_available_docs() -> list[str]:
+    """Return sorted list of doc names available in the installed package.
+
+    Returns:
+        Sorted list of doc stems (filenames without .md extension),
+        or an empty list if the doc directory cannot be found.
+    """
+    for doc_dir in [
+        Path(__file__).parent / "doc",
+        Path.cwd() / "src" / "dar_backup" / "doc",
+    ]:
+        if doc_dir.is_dir():
+            return sorted(p.stem for p in doc_dir.glob("*.md"))
+    return []
+
+
+def _doc_completer(prefix: str, **kwargs) -> list[str]:
+    """Argcomplete completer for --doc and --doc-pretty.
+
+    Args:
+        prefix: Characters typed so far.
+
+    Returns:
+        Doc stems that start with prefix.
+    """
+    return [name for name in _list_available_docs() if name.startswith(prefix)]
+
+
+def print_doc(name: str, pretty: bool = False) -> None:
+    """Print a documentation file from the installed doc/ directory.
+
+    Args:
+        name: Doc filename stem without .md extension (e.g. 'getting-started').
+        pretty: If True, render with rich Markdown formatting.
+
+    Raises:
+        SystemExit: If the named doc cannot be found.
+    """
+    candidates = [
+        Path(__file__).parent / "doc" / f"{name}.md",
+        Path.cwd() / "src" / "dar_backup" / "doc" / f"{name}.md",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            print_markdown(str(candidate), pretty=pretty)
+            return
+
+    available = _list_available_docs()
+    print(f"❌ Doc '{name}' not found.", file=stderr)
+    if available:
+        print(f"Available docs: {', '.join(available)}", file=stderr)
+    raise SystemExit(1)
+
+
 def list_definitions(backup_d_dir: str, *, allow_unsafe: bool = False) -> List[str]:
     """
     Return backup definition filenames from BACKUP.D_DIR, sorted by name.
@@ -2080,6 +2135,10 @@ def _sigterm_handler(signum, frame):
     parser.add_argument("--readme-pretty", action="store_true", help="Print README.md to stdout with Markdown styling and exit.")
     parser.add_argument("--changelog", action="store_true", help="Print Changelog.md to stdout and exit.")
     parser.add_argument("--changelog-pretty", action="store_true", help="Print Changelog.md to stdout with Markdown styling and exit.")
+    doc_arg = parser.add_argument("--doc", metavar="NAME", help="Print a documentation file by name and exit (use tab completion to list available docs).")
+    doc_arg.completer = _doc_completer
+    doc_pretty_arg = parser.add_argument("--doc-pretty", metavar="NAME", help="Print a documentation file with Markdown styling and exit.")
+    doc_pretty_arg.completer = _doc_completer
     parser.add_argument('-v', '--version', action='store_true', help="Show version and license information.")
 
     argcomplete.autocomplete(parser)
@@ -2116,6 +2175,12 @@ def _sigterm_handler(signum, frame):
     elif args.changelog_pretty:
         print_changelog(None, pretty=True)
         exit(0)
+    elif args.doc:
+        print_doc(args.doc, pretty=False)
+        exit(0)
+    elif args.doc_pretty:
+        print_doc(args.doc_pretty, pretty=True)
+        exit(0)
 
 
     config_settings_path = get_config_file(args)