fully document builders

tzk/__main__.py

@@ -45,13 +45,13 @@ class CommitCommand(CliCommand):
             "-m", "--message",
             metavar="MSG",
             help="Commit message to use.",
-            default=(cm().commit_message or "checkpoint")
+            default=cm().commit_message,
         )
         parser.add_argument(
             "-r", "--remote",
             metavar="REMOTE",
-            help="Name of the configured Git remote to push to.",
-            default=(cm().commit_remote or "origin"),
+            help="Name of the Git remote to push to.",
+            default=cm().commit_remote,
         )
         parser.add_argument(
             "-l", "--local",
@@ -70,8 +70,7 @@ class CommitCommand(CliCommand):
                      f"'{cm().commit_require_branch}' branch to commit.")
 
         git.exec("add", "-A")
-        git.exec("commit", "-m", args.message)
-        if not args.local:
+        if git.rc("commit", "-m", args.message) == 0 and args.remote and not args.local:
             git.exec("push", args.remote)
 
 
@@ -270,7 +269,7 @@ def chdir_to_wiki():
         os.chdir(cm().wiki_folder)
     except FileNotFoundError:
         fail(f"Tried to change directory into the wiki_folder '{cm().wiki_folder}' "
-            f"specified in your config file, but that directory does not exist.")
+             f"specified in your config file, but that directory does not exist.")
 
     if not os.path.exists("tiddlywiki.info"):
         fail(f"After changing directory into {cm().wiki_folder} per your config file: "

tzk/builders.py

@@ -1,19 +1,13 @@
 """
 *Builders* are small executable chunks that together can be linked into a useful build
-process. Aside from two helper functions (:func:`stop()` and :func:`info()`)
-to fail the build and display an informational message, respectively, all other
-functions in this module are builders.
+process.
 
-Builders are decorated with ``@tzk_builder``, a synonym for
-:func:`_lazy_evaluable()`, which causes them to be lazy-evaluated: that is,
-when they're initially called in the configuration, instead of running the
-function and returning its result, a zero-argument function with all of the
-arguments wrapped up is returned, to be run at a later time. This allows the
-configuration file to be read at any time to retrieve information about the
-defined products without actually running any build steps.
-
-You can write and use custom builders right within your config file
-by decorating them with ``@builders.tzk_builder``.
+Builders are decorated with :func:`tzk_builder`, which causes them to be
+lazy-evaluated: that is, when they're initially called in the configuration,
+instead of running the function and returning its result, a zero-argument
+function with all of the arguments wrapped up is returned, to be run at a later
+time. This allows the configuration file to be read at any time to retrieve
+information about the defined products without actually running any build steps.
 """
 
 from contextlib import contextmanager
@@ -139,7 +133,10 @@ def new_output_folder():
     assert 'public_wiki_folder' not in build_state
     build_state['public_wiki_folder'] = tempfile.mkdtemp()
 
-new_output_folder.cleaner = lambda: shutil.rmtree(build_state['public_wiki_folder'])
+def new_output_folder_cleaner():
+    if 'public_wiki_folder' in build_state:
+        shutil.rmtree(build_state['public_wiki_folder'])
+new_output_folder.cleaner = new_output_folder_cleaner
 
 
 @tzk_builder
@@ -232,7 +229,7 @@ def save_attachments_externally(attachment_filter: str = "[is[image]]",
     on each image tiddler to point to this new location.
     For the latter step, use the
     ``externalize_attachments``, ``attachment_filter``, and ``canonical_uri_template``
-    parameters to the ``compile_html_file`` step.
+    parameters to the :func:`compile_html_file` step.
 
     :param attachment_filter: The tiddlers to be saved to the external folder;
                               by default, ``[is[image]]``.
@@ -429,11 +426,13 @@ def set_tiddler_values(mappings: Dict[str, str]) -> None:
     flags or other wikitext solutions within the wiki -- for instance, changing the
     subtitle or what buttons are visible. It's also used to implement feature flags
     in the first place by changing the ``$:/config/sib/CurrentEditionPublicity``
-    tiddler to ``public``, so the minimal functional wiki will use:
-    
-    ```python
-    {'$__config_sib_CurrentEditionPublicity.tid': 'public',}
-    ```
+    tiddler to ``public``, so at minimum, the build of a public wiki should use:
+
+    .. code-block:: python
+
+        builders.set_tiddler_values({
+            '$__config_sib_CurrentEditionPublicity.tid': 'public',
+        })
 
     :param mappings: A dictionary whose keys are tiddler names
                      and whose values are the values to be inserted

tzk/config.py

@@ -14,6 +14,15 @@ from tzk.util import fail
 
 class ConfigurationManager:
     def __init__(self):
+        self.initialize_cm()
+
+    def __getattr__(self, attr):
+        if self.conf_mod is None:
+            return None
+        else:
+            return getattr(self.conf_mod, attr, None)
+
+    def initialize_cm(self):
         self.config_path = Path.cwd()
 
         for child in sorted(self.config_path.iterdir()):
@@ -29,12 +38,6 @@ class ConfigurationManager:
             # no config file
             self.conf_mod = None
 
-    def __getattr__(self, attr):
-        if self.conf_mod is None:
-            return None
-        else:
-            return getattr(self.conf_mod, attr, None)
-
     def has_config(self) -> bool:
         return self.conf_mod is not None
 

tzk/default_config.py

@@ -19,10 +19,12 @@ wiki_folder = "wiki"
 ### COMMITTING ####
 # Default commit message to use with 'tzk commit'.
 # You can always use 'tzk commit -m' to use a different message on the fly.
-commit_message = "daily checkpoint"
+commit_message = "checkpoint"
 
 # Git remote to push changes to when you run 'tzk commit'.
-commit_remote = "origin"
+# If you never want to push changes, set this to the empty string ("").
+commit_remote = ""
+#commit_remote = "origin"
 
 # Uncomment if you want to abort 'tzk commit' if you're not on a specific branch.
 #commit_require_branch = "master"
@@ -67,12 +69,13 @@ _public_export_filt = r"""
 # you can write your own, or you can run arbitrary shell commands
 # using a 'builders.shell("my shell command here"),' builder.
 products = {
-    # The default configuration contains a single product for building a public wiki.
+    # The default configuration contains a single product for building a public wiki;
+    # use 'tzk build public' to build it. You can add as many products as you want.
     'public': [
         builders.new_output_folder(),
-        builders.export_public_tiddlers(_public_export_filt),
+        builders.export_public_tiddlers(export_filter=_public_export_filt),
         builders.replace_private_people(),
-        builders.set_tiddler_values({
+        builders.set_tiddler_values(mappings={
             '$__config_sib_CurrentEditionPublicity.tid': 'public',
             '$__config_sib_IsPublicEdition.tid': 'false',
             '$__config_DefaultSidebarTab.tid': '$:/sib/SideBar/Explore',
@@ -97,4 +100,9 @@ products = {
         builders.save_attachments_externally(),
         builders.compile_html_file(externalize_attachments=True),
     ],
+    # If you want a second product, add it like this:
+    #'secondproduct': [
+    #    builders.new_output_folder(),
+    #    ... and so on ...
+    #],
 }