From e0ce7078942af705745081b51c4ee3b62719ae86 Mon Sep 17 00:00:00 2001
From: "Soren I. Bjornstad" <contact@sorenbjornstad.com>
Date: Fri, 27 Aug 2021 10:28:53 -0500
Subject: [PATCH] installation instructions, tzk preflight

---
 docs/configuration.rst | 15 ++++++++++
 docs/index.rst         |  3 +-
 docs/installation.rst  | 66 ++++++++++++++++++++++++++++++++++++++++++
 setup.py               |  4 ++-
 tzk/__main__.py        | 25 ++++++++++------
 tzk/util.py            | 15 ++++++++++
 6 files changed, 117 insertions(+), 11 deletions(-)
 create mode 100644 docs/configuration.rst
 create mode 100644 docs/installation.rst

diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..637891c
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,15 @@
+===============
+Configuring tzk
+===============
+
+Change into a directory you'd like to use as your Zettelkasten repository.
+The directory should be empty, so you'll probably want to create a new one, e.g.:
+
+```
+$ mkdir my_zettelkasten
+$ cd my_zettelkasten
+```
+
+Run ``tzk init``.
+This will install TiddlyWiki,
+set up a Git repository,
diff --git a/docs/index.rst b/docs/index.rst
index 6046cdd..f21774d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,7 @@
 tzk
 ===
 
-**tzk** (pronounced /tə.zɪːk/)
+**tzk** (pronounced /tə'zɪːk/)
 is a custom build tool and utility CLI
 for Soren Bjornstad's Zettelkasten edition of TiddlyWiki.
 
@@ -9,6 +9,7 @@ for Soren Bjornstad's Zettelkasten edition of TiddlyWiki.
    :maxdepth: 3
    :caption: Contents
 
+   installation
    operations
 
 
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..b3754de
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,66 @@
+==============
+Installing tzk
+==============
+
+
+tzk itself
+==========
+
+On most systems, tzk may be installed directly from pip at a command line:
+
+```
+$ pip install tzk
+```
+
+If you don't have Python 3.6 or greater on your computer,
+you'll need to install it first.
+If you aren't sure how to do that,
+here's an `exhaustive guide`_ to installing Python on all major operating systems.
+Once you've gotten Python installed,
+you'll be able to use ``pip`` to install tzk as described above.
+
+To check your work, run ``tzk --version``;
+you should see a version number rather than an error,
+something like:
+
+```
+$ tzk --version
+1.0.0
+```
+
+.. _exhaustive guide: https://realpython.com/installing-python/#how-to-install-python-on-macos
+
+
+Dependencies
+============
+
+In order to set up your Zettelkasten,
+you'll also need ``npm`` and ``git``.
+You can check if they're installed like this:
+
+```
+$ npm --version
+7.20.6
+$ git --version
+git version 2.32.0
+```
+
+Your versions will likely be a little different by the time you read this.
+As long as you get a version number, you're good;
+tzk does not use any features of either tool that require bleeding-edge versions.
+
+If you don't have **npm**,
+follow step 1 of the Node.js installation instructions in the `TiddlyWiki documentation`_.
+You can skip all the remaining steps -- tzk takes care of that part for you.
+
+If you don't have **git**,
+follow the steps in the `Installing Git`_ section of Pro Git.
+
+.. _TiddlyWiki documentation: https://tiddlywiki.com/#Installing%20TiddlyWiki%20on%20Node.js
+.. _Installing Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+
+
+Checking your work
+==================
+
+Run ``tzk preflight`` to double-check that everything is correctly installed.
diff --git a/setup.py b/setup.py
index e9817df..1084bd1 100644
--- a/setup.py
+++ b/setup.py
@@ -22,6 +22,8 @@ setuptools.setup(
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
         "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
         "Operating System :: OS Independent",
     ],
@@ -30,5 +32,5 @@ setuptools.setup(
             "tzk = tzk.__main__:launch"
         ],
     },
-    python_requires='>=3.8',
+    python_requires='>=3.6',
 )
diff --git a/tzk/__main__.py b/tzk/__main__.py
index fecb303..170f808 100644
--- a/tzk/__main__.py
+++ b/tzk/__main__.py
@@ -1,7 +1,6 @@
 from abc import ABC, abstractmethod, abstractclassmethod
 import argparse
 import os
-import shutil
 import sys
 import traceback
 from typing import Optional
@@ -9,7 +8,7 @@ from typing import Optional
 from tzk.config import cm
 from tzk import git
 from tzk import tw
-from tzk.util import BuildError, fail, numerize
+from tzk.util import BuildError, fail, numerize, require_dependencies
 
 
 class CliCommand(ABC):
@@ -141,13 +140,7 @@ class InitCommand(CliCommand):
         )
 
     def _precheck(self):
-        if shutil.which("npm") is None:
-            fail("TZK requires NPM. Please install NPM and make it available on your PATH.\n"
-                 "https://docs.npmjs.com/downloading-and-installing-node-js-and-npm")
-
-        if shutil.which("git") is None:
-            fail("TZK requires Git. Please install Git and make it available on your PATH.\n"
-                 "https://git-scm.com/book/en/v2/Getting-Started-Installing-Git")
+        require_dependencies()
 
         if os.path.exists("package.json"):
             fail("A 'package.json' file already exists in the current directory. "
@@ -158,6 +151,20 @@ class InitCommand(CliCommand):
         tw.install(args.wiki_name, args.tiddlywiki_version_spec, args.author)
 
 
+class PreflightCommand(CliCommand):
+    cmd = "preflight"
+    help = "Check if tzk and all its dependencies are correctly installed."
+
+    @classmethod
+    def setup_arguments(cls, parser: argparse.ArgumentParser) -> None:
+        pass
+
+    def execute(self, args: argparse.Namespace) -> None:
+        require_dependencies()
+        print("You're all set! Change into a directory you want to "
+              "turn into your tzk repository and run 'tzk init'.")
+
+
 class BuildCommand(CliCommand):
     cmd = "build"
     help = ("Build another wiki or derivative product, "
diff --git a/tzk/util.py b/tzk/util.py
index 8d170ad..4e76f31 100644
--- a/tzk/util.py
+++ b/tzk/util.py
@@ -3,6 +3,7 @@ util.py - miscellaneous utility functions
 """
 from contextlib import contextmanager
 import os
+import shutil
 import sys
 from typing import NoReturn
 
@@ -40,3 +41,17 @@ def pushd(directory: str):
         yield
     finally:
         os.chdir(old_directory)
+
+def require_dependencies() -> None:
+    """
+    Raise an exception if dependencies of tzk aren't available.
+    """
+    if shutil.which("npm") is None:
+        fail("npm is not available. "
+                "Please install NPM and make it available on your PATH.\n"
+                "https://docs.npmjs.com/downloading-and-installing-node-js-and-npm")
+
+    if shutil.which("git") is None:
+        fail("Git is not available. "
+                "Please install Git and make it available on your PATH.\n"
+                "https://git-scm.com/book/en/v2/Getting-Started-Installing-Git")
\ No newline at end of file