From 39df530ec2ead656a8a75d83d8af1c237184e59b Mon Sep 17 00:00:00 2001
From: "Soren I. Bjornstad" <contact@sorenbjornstad.com>
Date: Tue, 21 Sep 2021 12:07:15 -0500
Subject: [PATCH] improve help messages

---
 RELEASING.md    | 13 +++++++++++++
 tzk/__main__.py | 31 ++++++++++++++++++++++++++-----
 tzk/util.py     |  3 +++
 3 files changed, 42 insertions(+), 5 deletions(-)
 create mode 100644 RELEASING.md

diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 0000000..0938e62
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,13 @@
+1. Run 'tzk build emptify' in the parent directory;
+   this will update the single-file (for GitHub Pages)
+   and edition (for the PyPi package) versions.
+   Ensure that the emptified build looks how you want it.
+2. Update version numbers:
+   `setup.py`,
+   `cli_docs/conf.py`,
+   `util.py`.
+3. Push changes to GitHub.
+   Check that RTD and GitHub Pages update as desired
+   (https://tzk.readthedocs.io/en/latest/,
+    https://sobjornstad.github.io/tzk/).
+4. Run `publish.sh`, which will upload the latest package version to PyPi.
diff --git a/tzk/__main__.py b/tzk/__main__.py
index 3013f34..72f284e 100644
--- a/tzk/__main__.py
+++ b/tzk/__main__.py
@@ -10,7 +10,8 @@ from typing import Optional
 from tzk.config import cm, DEFAULT_INIT_OPTS
 from tzk import git
 from tzk import tw
-from tzk.util import BuildError, fail, numerize, require_dependencies, pushd
+from tzk.util import (BuildError, fail, numerize, require_dependencies, pushd,
+                      TZK_VERSION)
 
 
 class CliCommand(ABC):
@@ -78,7 +79,7 @@ class CommitCommand(CliCommand):
 
 class ListenCommand(CliCommand):
     cmd = "listen"
-    help = "Start a TiddlyWiki server in the current directory."
+    help = "Start a TiddlyWiki server in the current tzk repository."
 
     @classmethod
     def setup_arguments(cls, parser: argparse.ArgumentParser) -> None:
@@ -121,7 +122,7 @@ class ListenCommand(CliCommand):
 
 class InitCommand(CliCommand):
     cmd = "init"
-    help = "Set up a new tzk directory."
+    help = "Set up a new tzk repository."
 
     @classmethod
     def setup_arguments(cls, parser: argparse.ArgumentParser) -> None:
@@ -170,6 +171,18 @@ class PreflightCommand(CliCommand):
               "turn into your tzk repository and run 'tzk init'.")
 
 
+class VersionCommand(CliCommand):
+    cmd = "version"
+    help = "Find out what version your tzk is at."
+
+    @classmethod
+    def setup_arguments(cls, parser: argparse.ArgumentParser) -> None:
+        pass
+
+    def execute(self, args: argparse.Namespace) -> None:
+        print(f"tzk version {TZK_VERSION}")
+
+
 class BuildCommand(CliCommand):
     cmd = "build"
     help = ("Build another wiki or derivative product, "
@@ -386,11 +399,19 @@ def launch():
                  f"'{os.environ['TZK_DIRECTORY']}', so I tried to go there, "
                  f"but there's no tzk_config.py there either.")
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=f"TiddlyZettelKasten {TZK_VERSION} CLI\n"
+                    f"Copyright (c) 2021 Soren Bjornstad.\n"
+                    f"MIT license; see https://github.com/sobjornstad/tzk/LICENSE for details.",
+        epilog="For full documentation, see https://tzk.readthedocs.io/en/latest/.",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
 
     subparsers = parser.add_subparsers()
     for command in sorted(CliCommand.__subclasses__(), key=lambda i: i.__name__):
-        subparser = subparsers.add_parser(command.cmd, help=command.help)
+        subparser = subparsers.add_parser(command.cmd,
+                                          help=command.help,
+                                          description=command.help)
         subparser.set_defaults(_cls=command)
         command.setup_arguments(subparser)  # type: ignore
 
diff --git a/tzk/util.py b/tzk/util.py
index 62dd65f..ca725d2 100644
--- a/tzk/util.py
+++ b/tzk/util.py
@@ -10,6 +10,9 @@ import sys
 from typing import Any, Callable, Dict, NoReturn
 
 
+TZK_VERSION = "0.1.0"
+
+
 class BuildError(Exception):
     pass