reorganize to prepare for publish

cli_docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

cli_docs/builders.rst

@@ -0,0 +1,169 @@
+========
+Builders
+========
+
+.. currentmodule:: tzk.builders
+
+*Builders* are small executable chunks
+that can be linked together to form a useful build process.
+Products are built by applying builders in sequence.
+Please see the existing ``products`` dictionary and associated comments
+in the :ref:`config file <Configuring tzk>` for how these are specified.
+
+
+Builders included with tzk
+==========================
+
+You can use the following builders in your configuration file out of the box:
+
+.. autofunction:: check_for_kill_phrases
+
+.. autofunction:: compile_html_file
+
+.. autofunction:: delete_tiddlers
+
+.. autofunction:: editionify
+
+.. autofunction:: export_public_tiddlers
+
+.. autofunction:: new_output_folder
+
+.. autofunction:: publish_wiki_to_github
+
+.. autofunction:: replace_private_people
+
+.. autofunction:: require_branch
+
+.. autofunction:: require_clean_working_tree
+
+.. autofunction:: save_attachments_externally
+
+.. autofunction:: say_hi
+
+.. autofunction:: set_tiddler_values
+
+.. autofunction:: shell
+
+
+Builder helper functions
+========================
+
+These helper functions, also defined in :mod:`tzk.builders`,
+are intended for use with any custom builders you create.
+
+.. autofunction:: tzk.builders::info
+
+.. autofunction:: tzk.builders::stop
+
+.. autodecorator:: tzk.builders::tzk_builder
+
+
+Custom builders
+===============
+
+If the existing builders don't cover something you're hoping to do to build a product,
+you can write your own builder as a Python function directly within your config file.
+
+As an example, let's suppose that we want to publish our wiki to an S3 bucket
+fronted by CloudFront on Amazon Web Services.
+We can work with AWS using the ``aws`` CLI,
+if we've set that up on our computer
+(we could also use the ``boto3`` Python library,
+which is cleaner but slightly longer
+and requires us to muck around with ``pip``,
+so we'll do it through the CLI in this example).
+We first write a builder function decorated with :func:`builders.tzk_builder() <tzk_builder>`
+in our ``tzk_config.py``,
+anywhere above the ``products`` dictionary:
+
+.. code-block:: python
+
+    from pathlib import Path
+    import subprocess
+
+    @builders.tzk_builder
+    def publish_to_aws(target_uri: str, cloudfront_distribution_id: str):
+        "Publish output to Amazon S3"
+        source_folder = Path(builders.build_state['public_wiki_folder']) / "output"
+        # Sync the output folder to S3, deleting any files that have been removed.
+        subprocess.call(("aws", "s3", "sync", "--delete", source_folder, target_uri))
+        # Clear the CDN cache so the new version is available immediately.
+        subprocess.call(("aws", "cloudfront", "create-invalidation",
+                        "--distribution-id", cloudfront_distribution_id, "--paths", "/*"))
+
+``builders.build_state`` is a dictionary that is preserved across all build steps.
+The :func:`new_output_folder()` builder
+populates this ``public_wiki_folder`` attribute early in the default build process,
+so that it contains the path to the temporary wiki that build steps happen within.
+
+The first line of the docstring, in this case ``"Publish output to Amazon S3"``,
+is used as the description of the step in output, with any period at the end removed.
+
+Then we add a call to this builder within the list of steps for this product,
+with whatever parameters we like:
+
+.. code-block:: python
+    :emphasize-lines: 5
+
+    products = {
+        'public': [
+            [...]
+            builders.compile_html_file(externalize_attachments=True),
+            publish_to_aws("s3://my_target_uri", "MY_DISTRIBUTION_ID"),
+        ],
+    }
+
+Since we've parameterized this builder,
+we can easily use it multiple times if we want,
+for instance within different products.
+Note that we say just ``publish_to_aws``,
+not ``builders.publish_to_aws``,
+since this builder is located directly within the config file
+rather than in the external ``tzk.builders`` module that comes with tzk.
+
+.. tip::
+    If you do something in a builder that needs to be cleaned up later,
+    like creating a temporary file,
+    assign a cleanup function to the ``cleaner`` attribute of your builder:
+    ::
+
+        def aws_cleanup():
+            # nothing really needs to be cleaned up, but if it did we'd do it here
+            pass
+        publish_to_aws.cleaner = aws_cleanup
+
+    Cleanup functions will run after all steps are done,
+    regardless of whether the build succeeds or fails.
+
+
+Shell commands
+==============
+
+If a custom builder seems like overkill
+or you're not familiar with Python,
+you can also run simple shell commands using the :func:`shell()` builder.
+
+Our AWS example would look like this:
+
+.. code-block:: python
+    :emphasize-lines: 5-7
+
+    products = {
+        'public': [
+            [...]
+            builders.compile_html_file(externalize_attachments=True,
+                                       output_folder="output/public_site/"),
+            builders.shell("aws s3 sync --delete output/public_site s3://my_target_uri"),
+            builders.shell("aws cloudfront create-invalidation --distribution-id MY_DISTRIBUTION_ID --paths '/*'"),
+        ],
+    }
+
+Notice the need to include quotes within the string in :func:`shell`;
+the same quoting rules as when running shell commands directly apply.
+Also notice that we had to access the compiled HTML file from
+``output/public_site``,
+since we can no longer refer to the ``build_state`` dictionary
+to learn where the temporary output folder is.
+Paths are relative to the private wiki's root directory
+(the directory containing the ``tiddlywiki.info`` file)
+while builders are running.

cli_docs/conf.py

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+# Instead of adding things manually to the path, we just ensure we install esc
+# in editable mode in our environment.
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'tzk'
+copyright = '2021 Soren Bjornstad'
+author = 'Soren Bjornstad'
+
+# The short X.Y version
+version = "0.1.0"
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '1.8.5'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+
+# -- Extension configuration -------------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# Prefix section labels with the names of their documents, to avoid ambiguity
+# when the same heading appears on several pages.
+autosectionlabel_prefix_document = False

cli_docs/configuration.rst

@@ -0,0 +1,71 @@
+===============
+Configuring tzk
+===============
+
+Basic setup
+===========
+
+1. 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
+
+2. Run ``tzk init``.
+   This will create a tzk configuration file,
+   install TiddlyWiki to this folder,
+   and set up a Git repository.
+
+3. When ``init`` has completed successfully,
+   open the ``tzk_config.py`` in your favorite text editor.
+   Read the comments and make any changes you would like.
+   See the :ref:`Builders` section of this documentation
+   for more information about builders --
+   but you'll most likely want to get started with your wiki now
+   and worry about builds once you actually have some content to build!
+
+4. Run ``tzk listen`` and confirm that you can access your wiki.
+
+
+Committing
+==========
+
+Many people find that carefully designing atomic Git commits
+when editing a TiddlyWiki
+is difficult and not all that useful,
+so the ``tzk commit`` command is made available
+to quickly stage, commit, and (if you wish) push all changes in the repository in one go.
+
+If you want to push your changes to some remote location,
+such as a GitHub repository,
+add a new Git remote (e.g., ``git remote add origin https://github.com/you/YourRepository``)
+and set the ``commit_remote`` option in your tzk config to the remote name
+(here, ``origin``).
+You can selectively skip pushing for a particular commit
+with the ``--local`` switch to ``tzk commit``.
+
+.. note::
+   If you want to push a wiki that contains only some of your content
+   to GitHub in a form that others can browse,
+   don't try to set it up here --
+   use a :func:`publish_wiki_to_github() <tzk.builders.publish_wiki_to_github>` builder
+   at the end of the ``public`` build product.
+   See :ref:`Builders` for more information.
+
+
+Environment
+===========
+
+If you'd like to be able to run ``tzk`` from any directory,
+rather than having to change into the directory of your tzk repository,
+set the ``TZK_DIRECTORY`` environment variable on your system
+to its full path.
+If the current directory contains a ``tzk_config.py`` file,
+the current directory will still be preferred to the ``TZK_DIRECTORY`` directory.
+
+.. note::
+    ``TZK_DIRECTORY`` is not honored when calling ``tzk init``.
+    Otherwise tzk would prioritize the ``TZK_DIRECTORY`` over the current directory
+    since the current directory doesn't contain a config file yet,
+    and it would be impossible to initialize a second tzk repository.

cli_docs/index.rst

@@ -0,0 +1,22 @@
+tzk
+===
+
+**tzk** (pronounced /tə'ziːk/, tuh-ZEEK)
+is a build tool and utility CLI
+for Soren Bjornstad's Zettelkasten edition of TiddlyWiki.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents
+
+   installation
+   configuration
+   builders
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

cli_docs/installation.rst

@@ -0,0 +1,63 @@
+==============
+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 rather than an error, 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.