Merge pull request #149 from opengisch/upgrade

Add Upgrade capability

Author: 3nids

docs/docs/cli.md

@@ -1,20 +1,15 @@
-usage: create_cli_help.py [-h] [-c CONFIG_FILE] -s PG_SERVICE [-d DIR] [-v] [--version]
-- `{info,install,role,check,dump,restore,baseline,upgrade} ...`
-
+usage: update_cli_docs.py [-h] [-c CONFIG_FILE] -s PG_SERVICE [-d DIR] [-v] [--version]
+{info,install,role,check,dump,restore,baseline,upgrade} ...
 ### options:
 - `-h, --help`: show this help message and exit
-- `-c CONFIG_FILE, --config_file CONFIG_FILE`
-- `set the config file. Default: .pum.yaml`
-- `-s PG_SERVICE, --pg-service PG_SERVICE`
-- `Name of the postgres service`
+- `-c CONFIG_FILE, --config_file CONFIG_FILE`: set the config file. Default: .pum.yaml
+- `-s PG_SERVICE, --pg-service PG_SERVICE`: Name of the postgres service
 - `-d DIR, --dir DIR`: Directory or URL of the module. Default: .
 - `-v, --verbose`: Increase output verbosity (e.g. -v, -vv)
 - `--version`: Show program's version number and exit.
-
 ### commands:
-- `valid pum commands`
-
-- `{info,install,role,check,dump,restore,baseline,upgrade}`
+valid pum commands
+{info,install,role,check,dump,restore,baseline,upgrade}
 - `info`: show info about schema migrations history.
 - `install`: Installs the module.
 - `role`: manage roles in the database

docs/docs/cli/baseline.md

@@ -1,6 +1,4 @@
-usage: create_cli_help.py baseline [-h] -b BASELINE
-
+usage: update_cli_docs.py baseline [-h] -b BASELINE
 ### options:
 - `-h, --help`: show this help message and exit
-- `-b BASELINE, --baseline BASELINE`: set baseline in the format x.x.x
-- `--create-table`: create the pum_migrations table if it does not exist
+- `-b BASELINE, --baseline BASELINE`: Set baseline in the format x.x.x

docs/docs/cli/check.md

@@ -1,14 +1,9 @@
-usage: create_cli_help.py check [-h]
-- `[-i {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...]]`
-- `[-N EXCLUDE_SCHEMA] [-P EXCLUDE_FIELD_PATTERN] [-o OUTPUT_FILE]`
-
+usage: update_cli_docs.py check [-h]
+[-i {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...]]
+[-N EXCLUDE_SCHEMA] [-P EXCLUDE_FIELD_PATTERN] [-o OUTPUT_FILE]
 ### options:
 - `-h, --help`: show this help message and exit
-- `-i {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...], --ignore {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...]`
-- `Elements to be ignored`
-- `-N EXCLUDE_SCHEMA, --exclude-schema EXCLUDE_SCHEMA`
-- `Schema to be ignored.`
-- `-P EXCLUDE_FIELD_PATTERN, --exclude-field-pattern EXCLUDE_FIELD_PATTERN`
-- `Fields to be ignored based on a pattern compatible with SQL LIKE.`
-- `-o OUTPUT_FILE, --output_file OUTPUT_FILE`
-- `Output file`
+- `-i {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...], --ignore {tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} [{tables,columns,constraints,views,sequences,indexes,triggers,functions,rules} ...]`: Elements to be ignored
+- `-N EXCLUDE_SCHEMA, --exclude-schema EXCLUDE_SCHEMA`: Schema to be ignored.
+- `-P EXCLUDE_FIELD_PATTERN, --exclude-field-pattern EXCLUDE_FIELD_PATTERN`: Fields to be ignored based on a pattern compatible with SQL LIKE.
+- `-o OUTPUT_FILE, --output_file OUTPUT_FILE`: Output file

docs/docs/cli/dump.md

@@ -1,8 +1,6 @@
-usage: create_cli_help.py dump [-h] [-f {DumpFormat.CUSTOM,DumpFormat.PLAIN}] [-N EXCLUDE_SCHEMA] file
-
+usage: update_cli_docs.py dump [-h] [-f {DumpFormat.CUSTOM,DumpFormat.PLAIN}] [-N EXCLUDE_SCHEMA] file
 ### positional arguments:
 - `file`: The backup file
-
 ### options:
 - `-h, --help`: show this help message and exit
 - `-f {DumpFormat.CUSTOM,DumpFormat.PLAIN}, --format {DumpFormat.CUSTOM,DumpFormat.PLAIN}`: Dump format. Choices: ['custom', 'plain']. Default: plain.

docs/docs/cli/info.md

@@ -1,4 +1,3 @@
-usage: create_cli_help.py info [-h]
-
+usage: update_cli_docs.py info [-h]
 ### options:
 - `-h, --help`: show this help message and exit

docs/docs/cli/install.md

@@ -1,10 +1,10 @@
-usage: create_cli_help.py install [-h] [-p PARAMETER PARAMETER] [--max-version MAX_VERSION] [-r] [-g]
-
+usage: update_cli_docs.py install [-h] [-p PARAMETER PARAMETER] [--max-version MAX_VERSION] [-r] [-g]
+[-d DEMO_DATA] [--beta-testing]
 ### options:
 - `-h, --help`: show this help message and exit
-- `-p PARAMETER PARAMETER, --parameter PARAMETER PARAMETER`
-- `Assign variable for running SQL deltas. Format is name value.`
-- `--max-version MAX_VERSION`
-- `maximum version to install`
+- `-p PARAMETER PARAMETER, --parameter PARAMETER PARAMETER`: Assign variable for running SQL deltas. Format is name value.
+- `--max-version MAX_VERSION`: maximum version to install
 - `-r, --roles`: Create roles
 - `-g, --grant`: Grant permissions to roles
+- `-d DEMO_DATA, --demo-data DEMO_DATA`: Load demo data with the given name
+- `--beta-testing`: This will install the module in beta testing, meaning that it will not be possible to receive any future updates.

docs/docs/cli/restore.md

@@ -1,10 +1,7 @@
-usage: create_cli_help.py restore [-h] [-x] [-N EXCLUDE_SCHEMA] file
-
+usage: update_cli_docs.py restore [-h] [-x] [-N EXCLUDE_SCHEMA] file
 ### positional arguments:
 - `file`: The backup file
-
 ### options:
 - `-h, --help`: show this help message and exit
 - `-x`: ignore pg_restore errors
-- `-N EXCLUDE_SCHEMA, --exclude-schema EXCLUDE_SCHEMA`
-- `Schema to be ignored.`
+- `-N EXCLUDE_SCHEMA, --exclude-schema EXCLUDE_SCHEMA`: Schema to be ignored.

docs/docs/cli/role.md

@@ -1,8 +1,6 @@
-usage: create_cli_help.py role [-h] {create,grant,revoke,drop}
-
+usage: update_cli_docs.py role [-h] {create,grant,revoke,drop}
 ### positional arguments:
-- `{create,grant,revoke,drop}`
-- `Action to perform`
-
+{create,grant,revoke,drop}
+Action to perform
 ### options:
 - `-h, --help`: show this help message and exit

docs/docs/cli/upgrade.md

@@ -1,8 +1,5 @@
-usage: create_cli_help.py upgrade [-h] [-u MAX_VERSION] [-p PARAMETER PARAMETER]
-
+usage: update_cli_docs.py upgrade [-h] [-u MAX_VERSION] [-p PARAMETER PARAMETER]
 ### options:
 - `-h, --help`: show this help message and exit
-- `-u MAX_VERSION, --max-version MAX_VERSION`
-- `upper bound limit version`
-- `-p PARAMETER PARAMETER, --parameter PARAMETER PARAMETER`
-- `Assign variable for running SQL deltas. Format is: name value.`
+- `-u MAX_VERSION, --max-version MAX_VERSION`: upper bound limit version
+- `-p PARAMETER PARAMETER, --parameter PARAMETER PARAMETER`: Assign variable for running SQL deltas. Format is: name value.

docs/update_cli_docs.py

@@ -1,13 +1,30 @@
 #!/usr/bin/env python3
+"""Generate Markdown documentation from the CLI argparse help output.
+
+This script renders the `pum` CLI help (and each subcommand help) into Markdown.
+It also normalizes wrapped help text so option/parameter descriptions are
+single-line in the generated docs.
+"""
+
 import argparse
 import io
 import contextlib
+import re
 
 from pum.cli import create_parser
 from pathlib import Path
 
 
 def parser_to_markdown(parser: argparse.ArgumentParser) -> str:
+    """Convert an argparse parser's help text to Markdown.
+
+    Args:
+        parser: The argparse parser to render.
+
+    Returns:
+        The generated Markdown string.
+
+    """
     buf = io.StringIO()
     with contextlib.redirect_stdout(buf):
         parser.print_help()
@@ -16,17 +33,55 @@ def parser_to_markdown(parser: argparse.ArgumentParser) -> str:
     # Simple Markdown formatting
     lines = help_text.strip().splitlines()
     md_lines = []
+    entry_re = re.compile(r"^\s{2,}(?P<key>\S.*?)\s{2,}(?P<desc>.+)$")
+
+    def norm(text: str) -> str:
+        # Collapse any wrapping/newlines/tabs into single spaces.
+        return " ".join(text.split())
+
+    last_entry_index: int | None = None
     for line in lines:
-        if line.strip().endswith(":"):
-            md_lines.append(f"### {line.strip()}")
-        elif line.startswith("  "):  # typically an argument line
-            parts = line.strip().split("  ", 1)
-            if len(parts) == 2:
-                md_lines.append(f"- `{parts[0]}`: {parts[1].strip()}")
+        stripped = line.rstrip("\n")
+        if not stripped:
+            continue
+
+        indent = len(stripped) - len(stripped.lstrip(" "))
+
+        # Section headers from argparse typically end with ':' and are not indented.
+        if stripped.strip().endswith(":") and not stripped.startswith(" "):
+            md_lines.append(f"### {stripped.strip()}")
+            last_entry_index = None
+            continue
+
+        match = entry_re.match(stripped)
+        if match:
+            key = match.group("key").strip()
+            desc = norm(match.group("desc"))
+            md_lines.append(f"- `{key}`: {desc}")
+            last_entry_index = len(md_lines) - 1
+            continue
+
+        # Some argparse formats print the option/arg key on its own line, with the
+        # description starting on the next (more-indented) line.
+        if indent >= 2 and indent <= 4:
+            key_only = stripped.strip()
+            if key_only.startswith("-") and not key_only.endswith(":"):
+                md_lines.append(f"- `{key_only}`:")
+                last_entry_index = len(md_lines) - 1
+                continue
+
+        # Wrapped description lines are indented, but don't start a new entry.
+        if stripped.startswith(" ") and last_entry_index is not None:
+            addition = norm(stripped)
+            if md_lines[last_entry_index].endswith(":"):
+                md_lines[last_entry_index] = f"{md_lines[last_entry_index]} {addition}"
             else:
-                md_lines.append(f"- `{line.strip()}`")
-        else:
-            md_lines.append(line.strip())
+                md_lines[last_entry_index] = f"{md_lines[last_entry_index]} {addition}"
+            continue
+
+        # Plain text paragraph.
+        md_lines.append(stripped.strip())
+        last_entry_index = None
     return "\n".join(md_lines)