nicer doc fonts

.milpa/commands/itself/docs/html.sh

@@ -42,15 +42,24 @@ if [[ "$MILPA_ARG_ACTION" == "serve" ]]; then
   fi
 
   @milpa.log info "Launching hugo website generator with $MILPA_OPT_IMAGE"
+
+  templateDir=()
+  if [[ "$MILPA_OPT_TEMPLATE" != "" ]]; then
+    tplDir="$(cd "$MILPA_OPT_TEMPLATE" && pwd)" || @milpa.fail "--template is not a directory"
+    templateDir=(
+      -v "$tplDir/theme:/src/themes/cli/"
+      -v "$tplDir/config.toml:/src/config.toml"
+    )
+  fi
+
   containerID="$(docker run --rm -it \
     --name milpa_docs \
     --detach \
     -p "$MILPA_OPT_PORT:$MILPA_OPT_PORT" \
     -v "$content:/src/content/" \
+    "${templateDir[@]}" \
     "$MILPA_OPT_IMAGE" serve --debug --port "$MILPA_OPT_PORT")" || @milpa.fail "Could not spin up website generator"
     # to debug add:
-    # -v "${MILPA_ROOT}/repos/internal/docs/.template/theme:/src/themes/cli/" \
-    # -v "${MILPA_ROOT}/repos/internal/docs/.template/config.toml:/src/config.toml" \
 
   docker logs --follow milpa_docs &
 

.milpa/commands/itself/docs/html.yaml

@@ -22,3 +22,5 @@ options:
   hostname:
     default: milpa.dev
     description: The hostname to set as base for the rendered docs
+  template:
+    description: a local template to use instead of the default when serving

.milpa/docs/milpa/alternatives.md

@@ -4,24 +4,24 @@ description: Use-cases and alternatives when using milpa
 weight: 2
 ---
 
-I built milpa with a few use cases in mind:
+I built `milpa` with a few use cases in mind:
 
 - To **share groups of scripts** used by a group of folks in an engineering team (i.e. setup development environments, work with secrets/credentials)
 - to **share context and code**, without having to ask folks to run stuff off READMEs (i.e. pull service logs, forward ports), and
 - to **quickly build scripts** that will be documented sufficiently well for my forgetful future-self.
 
-I have used/would use milpa for:
+I have used/would use `milpa` for:
 
 - managing homelab services: building and deploying them, looking at their status and logs. From my personal device or CI.
 - bootstrapping engineering laptops: no need to follow a README, you get the right development environment for your os/arch, your credentials setup and the code ready for you to dive in.
 - every-day dev workflow: connect to vpn, get credentials for a database, maybe `--connect` directly to it, abstract away all those weird cloud provider APIs and CLIs, create releases.
 - organize all those odd, one-off-but-not-really commands: all those shells scripts, quick ruby scripts, perl hacks and jq monstrosities can have a nice home.
 
-milpa is great for these things, since it only requires Bash and a supported OS/arch but will setup and work with whatever your team likes using (today and beyond). milpa does the work of parsing arguments, validating them, offering help when things go sideways and so on, so these small scripts remain just so: small scripts.
+`milpa` is great for these things, since it only requires Bash and a supported OS/arch but will setup and work with whatever your team likes using (today and beyond). `milpa` does the work of parsing arguments, validating them, offering help when things go sideways and so on, so these small scripts remain just so: small scripts.
 
 See [unRob/nidito](https://github.com/unRob/nidito/tree/master/.milpa) for a working example, and/or the drop that that spilled the cup and got me to work on `milpa`.
 
-## milpa is great for
+## `milpa` is great for
 
 - working with small programs meant to be used as either building blocks for other programs, or user-facing collections of these blocks
 - sharing related commands using your team's source control versioning system, allowing anyone to mess with them and test them often
@@ -31,13 +31,13 @@ Tasks like bootstrapping development environments are usually left out for the u
 
 My aim is to make following the [Command Line Interface Guidelines](https://clig.dev) require as little effort as possible.
 
-## Where milpa won't shine
+## Where `milpa` won't shine
 
-I haven't tested the performance beyond dozens of repos with dozens of commands, and that being said, I can't see myself using milpa for anything more complex than that. I'd usually reach for another language to build a domain-specific CLI, specially if working with a team that is not very comfortable with shell scripting.
+I haven't tested the performance beyond dozens of repos with dozens of commands, and that being said, I can't see myself using `milpa` for anything more complex than that. I'd usually reach for another language to build a domain-specific CLI, specially if working with a team that is not very comfortable with shell scripting.
 
-When there's a need to distribute stand-alone CLI programs. milpa is not the best platform to package and distribute CLIs. Complex argument parsing and auto completion are also not in my roadmap; these are very valid use cases, but keeping a simple spec that works for most cases is going to create some friction for the least-common path.
+When there's a need to distribute stand-alone CLI programs. `milpa` is not the best platform to package and distribute CLIs. Complex argument parsing and auto completion are also not in my roadmap; these are very valid use cases, but keeping a simple spec that works for most cases is going to create some friction for the least-common path.
 
-When the primary runner of commands is not gonna be a human. Sorry robot friends! milpa's features are oriented primarily towards improving the experience of maintaining and running scripts by humans, and while there's nothing wrong with having an automated system (say CI, for example) run milpa commands, there is an overhead to consider by invoking `milpa` (both cognitive overhead and in terms of resource usage).
+When the primary runner of commands is not gonna be a human. Sorry robot friends! `milpa`'s features are oriented primarily towards improving the experience of maintaining and running scripts by humans, and while there's nothing wrong with having an automated system (say CI, for example) run `milpa` commands, there is an overhead to consider by invoking `milpa` (both cognitive overhead and in terms of resource usage).
 
 ## Okay, so what about...
 
@@ -55,11 +55,11 @@ There's some amazing tools out there, such as:
 - [Sub](https://github.com/basecamp/sub)
 - [Basher package manager](https://github.com/basherpm/basher)
 
-These all serve different purposes, and there is some feature overlap. milpa aims to provide the same level of support to non-bash scripts (hello applescript) without the need for another runtime to be installed. These projects are great for distributing and packaging software that may be used beyond your organization, while milpa aims to help smaller user bases, such as engineering teams, keep their shared scripts organized and up-to-date.
+These all serve different purposes, and there is some feature overlap. `milpa` aims to provide the same level of support to non-bash scripts (hello applescript) without the need for another runtime to be installed. These projects are great for distributing and packaging software that may be used beyond your organization, while `milpa` aims to help smaller user bases, such as engineering teams, keep their shared scripts organized and up-to-date.
 
 ### Make
 
-Make is great! I love using `make` for building artifacts, but I always end up hacking around it and wishing I had all of Make's strengths and the expressiveness of bash. I used `make` to build milpa initially since it's really a great tool, has a huge user base and flavors of it produce software used by millions. That being said, organizing makefiles and dealing with arguments is not something I can say I enjoy, and producing anything other than artifacts to the filesystem with Make doesn't feel right to me.
+Make is great! I love using `make` for building artifacts, but I always end up hacking around it and wishing I had all of Make's strengths and the expressiveness of bash. I used `make` to build `milpa` initially since it's really a great tool, has a huge user base and flavors of it produce software used by millions. That being said, organizing makefiles and dealing with arguments is not something I can say I enjoy, and producing anything other than artifacts to the filesystem with Make doesn't feel right to me.
 
 ### BYOCLI
 

.milpa/docs/milpa/internals.md

@@ -3,13 +3,15 @@ description: Summary of how milpa works
 weight: 50
 ---
 
-`milpa` is a bash script in charge of setting environment variables and handing off to the user-requested script. Most of the heavy lifting, including argument/option parsing and validation, as well as finding commands, is done by a companion binary named `compa` (a slang term for friend).
+`milpa` is a bash script in charge of setting environment variables and handing off to the user-requested script. Most of the heavy lifting, including argument/option parsing and validation, as well as finding commands, is done by a companion binary named `compa` (a slang term for friend in spanish).
 
-Milpa is built with, and thanks to:
+`milpa` is built with, and thanks to:
 
 - [bash](https://www.gnu.org/software/bash/)
 - [spf13/cobra](https://cobra.dev)
 
+## How it works
+
 ### `milpa` sets the stage
 
 1. As it starts running, milpa will set `MILPA_ROOT`, exit unless it points to an existing directory,
@@ -40,10 +42,12 @@ Milpa is built with, and thanks to:
 
 Mostly based on Bash's [Appendix E](https://tldp.org/LDP/abs/html/exitcodes.html) and FreeBSD's [`sysexits`](https://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD+4.3-RELEASE&format=html)
 
-- 2: `@milpa.fail` was called
-- 42: `compa` is requesting pretty printing and a clean `milpa` exit
-- 64: arguments/flags could not be parsed or failed validation
-- 70: a spec could not be parsed or help failed rendering
-- 78: `MILPA_ROOT` points to something that's not a directory, or `MILPA_PATH` has an incorrect path set
-- 127: sub-command not found
+| code  | reason |
+|-------|--------|
+| `2`   | `@milpa.fail` was called |
+| `42`  | `compa` is requesting pretty printing and a clean `milpa` exit |
+| `64`  | arguments/flags could not be parsed or failed validation |
+| `70`  | a spec could not be parsed or help failed rendering |
+| `78`  | `MILPA_ROOT` points to something that's not a directory, or `MILPA_PATH` has an incorrect path set |
+| `127` | sub-command not found |
 

.milpa/util/tmp.sh

@@ -1,4 +1,16 @@
-#!/bin/env bash
+#!/usr/bin/env bash
+# Copyright © 2021 Roberto Hidalgo <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 declare -a _tmp_files_created
 

README.md

@@ -1,8 +1,8 @@
 # milpa
 
-[`milpa`](https://milpa.dev) is a command-line tool to care for one's own garden of scripts, its name comes from ["milpa"](https://en.wikipedia.org/wiki/Milpa), an agricultural method that combines multiple crops in close proximity
+[`milpa`](https://milpa.dev) is a command-line tool to care for one's own garden of scripts. [Its name](https://en.wikipedia.org/wiki/Milpa) comes from an agricultural method that combines multiple crops in close proximity.
 
-For a brief intro to get started, check out [milpa help docs milpa quick-guide](/.milpa/docs/milpa/quick-guide.md).
+For a brief introductory tutorial, check out [milpa help docs milpa quick-guide](/.milpa/docs/milpa/quick-guide.md).
 
 ```sh
 # install on mac and linux with:

internal/actions/root.go

@@ -74,7 +74,7 @@ var rootcc = &cobra.Command{
 
 var Root = &command.Command{
 	Summary: "Runs commands found in " + _c.RepoRoot + " folders",
-	Description: `﹅milpa﹅ is a command-line tool to care for one's own garden of scripts, its name comes from "milpa", an agricultural method that combines multiple crops in close proximity. You and your team write scripts and a little spec for each command -use bash, or any other language-, and ﹅milpa﹅ provides autocompletions, sub-commands, argument parsing and validation so you can skip the toil and focus on your scripts.
+	Description: `﹅milpa﹅ is a command-line tool to care for one's own garden of scripts, its name comes from an agricultural method that combines multiple crops in close proximity. You and your team write scripts and a little spec for each command -use bash, or any other language-, and ﹅milpa﹅ provides autocompletions, sub-commands, argument parsing and validation so you can skip the toil and focus on your scripts.
 
   See [﹅milpa help docs milpa﹅](/.milpa/docs/milpa/index.md) for more information about ﹅milpa﹅`,
 	Meta: command.Meta{
@@ -97,11 +97,13 @@ var Root = &command.Command{
 		},
 		"no-color": &command.Option{
 			Type:        "bool",
-			Description: "Print to stderr without any formatting codes",
+			Description: "Disable printing of colors to stderr",
+			Default:     !runtime.ColorEnabled(),
 		},
 		"color": &command.Option{
 			Type:        "bool",
-			Description: "Print to stderr without any formatting codes",
+			Description: "Always print colors to stderr",
+			Default:     runtime.ColorEnabled(),
 		},
 		"silent": &command.Option{
 			Type:        "bool",
@@ -117,29 +119,43 @@ var Root = &command.Command{
 func RootCommand(version string) *cobra.Command {
 	rootcc.Annotations["version"] = version
 	rootFlagset := pflag.NewFlagSet("compa", pflag.ContinueOnError)
-	rootFlagset.BoolP("verbose", "v", runtime.VerboseEnabled(), "Log verbose output to stderr")
-	rootFlagset.Bool("silent", false, "Do not print any logs to stderr")
-	rootFlagset.BoolP("help", "h", false, "Display help for any command")
-	rootFlagset.Bool("no-color", !runtime.ColorEnabled(), "Do not print any formatting codes")
-	rootFlagset.Bool("color", runtime.ColorEnabled(), "Do not print any formatting codes")
-	rootFlagset.Bool("skip-validation", false, "Do not validate any arguments or options")
+	for name, opt := range Root.Options {
+		if opt.Type != "bool" {
+			continue
+		}
+		def, ok := opt.Default.(bool)
+		if !ok {
+			def = false
+		}
+
+		if opt.ShortName != "" {
+			rootFlagset.BoolP(name, opt.ShortName, def, opt.Description)
+		} else {
+			rootFlagset.Bool(name, def, opt.Description)
+		}
+	}
+
 	rootFlagset.Usage = func() {}
 	rootFlagset.SortFlags = false
-
 	rootcc.PersistentFlags().AddFlagSet(rootFlagset)
+
 	rootcc.Flags().Bool("version", false, "Display the version of milpa")
 
 	rootcc.CompletionOptions.DisableDefaultCmd = true
+
 	rootcc.AddCommand(versionCommand)
 	rootcc.AddCommand(completionCommand)
 	rootcc.AddCommand(generateDocumentationCommand)
 	rootcc.AddCommand(doctorCommand)
+
 	doctorCommand.Flags().Bool("summary", false, "")
 	rootcc.AddCommand(fetchRemoteRepo)
 	rootcc.AddCommand(introspectCommand)
+
 	introspectCommand.Flags().Int32("depth", 15, "")
 	introspectCommand.Flags().String("format", "json", "")
 	introspectCommand.Flags().String("template", "{{ indent . }}{{ .Name }} - {{ .Summary }}\n", "")
+
 	rootcc.SetHelpCommand(helpCommand)
 	helpCommand.AddCommand(docsCommand)
 	docsCommand.SetHelpFunc(docs.HelpRenderer(Root.Options))