Add support for shell documentation (cloudposse#467)

osterman · web-flow · commit 9f0f8d4c8b6c · 2019-05-06T23:01:46.000-07:00
* Add support for shell documentation

* Use front matter instead

* formatting

* fix formatting

* add fzf support

* Update formatting

* fix typo

* Update rootfs/usr/local/bin/docs

Co-Authored-By: osterman &lt;erik@cloudposse.com&gt;
diff --git a/Dockerfile b/Dockerfile
@@ -231,8 +231,15 @@ ENV XDG_CONFIG_HOME=/etc
 # Clean up file modes for scripts
 RUN find ${XDG_CONFIG_HOME} -type f -name '*.sh' -exec chmod 755 {} \;
 
+# Install "root" filesystem
 COPY rootfs/ /
 
+# Install documentation
+COPY docs/ /usr/share/docs/
+
+# Build man pages
+RUN /usr/local/bin/docs update
+
 WORKDIR /conf
 
 ENTRYPOINT ["/bin/bash"]
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,61 @@
+---
+title: README(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
+
+## NAME
+
+README - Documentation for Geodesic
+
+## SYNOPSIS
+ 
+This directory contains a number of markdown-formatted "man" pages. These will be available inside of the container.
+
+## USAGE
+
+### Build
+
+To rebuild the man pages, run `docs update`
+
+### List
+
+To list all available man pages, run `help`. Then for more information on any topic, run `help` and pass the command as an argument. 
+
+### Search 
+
+To search for help, run `help "topic"` where `"topic"` is what you want more information on.
+
+## CONTRIBUTING
+
+All documentation for `geodesic` belongs in the `docs/` folder. Use markdown appropriate formatting and styles. 
+
+## LAYOUT
+
+In order to be consistent with UNIX Man pages, all section titles should be *UPPERCASE* and begin with a single `##`. 
+Subsections should be properly capitalized and use `###`. Avoid going more than (2) sections deep.
+
+Use standard section names. 
+
+### Here are some examples.
+
+- `## NAME` The name of the command or function, followed by a one-line description of what it does.
+- `## SYNOPSIS` In the case of a command, a formal description of how to run it and what command line options it takes. For program functions, a list of the parameters the function takes and which header file contains its declaration.
+- `## DESCRIPTION` A textual description of the functioning of the command or function.
+- `## EXAMPLES` Some examples of common usage.
+- `## SEE ALSO` A list of related commands or functions.
+- `## OPTIONS` A list of supported options for the command
+- `## SYNTAX` An explation of the command's syntax
+- `## ENVIRONMENT` A list of supported environment variables
+- `## RETURN VALUES` A breakdown of the expected return values or exit codes
+- `## STANDARDS` Some of the "best practices"
+- `## SECURITY CONSIDERATIONS` Recommended settings for safer operation
+- `## BUGS` Some known issues
+- `## HISTORY` Background on command to give readers more context
+
+
+# SEE ALSO
+- https://pandoc.org/MANUAL.html
+- https://en.wikipedia.org/wiki/Man_page
+- https://en.wikipedia.org/wiki/RTFM
diff --git a/docs/about.md b/docs/about.md
@@ -1,12 +1,23 @@
-## Features
+---
+title: ABOUT(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
+
+## NAME
+
+about - About the Geodesic Cloud Automation Shell
+
+## FEATURES
 
 * **Secure** - TLS/PKI, OAuth2, MFA Everywhere, remote access VPN, [ultra secure bastion/jumphost](https://github.com/cloudposse/bastion) with audit capabilities and slack notifications, [IAM assumed roles](https://github.com/99designs/aws-vault/), automatic key rotation, encryption at rest, and VPCs
 * **Repeatable** - 100% Infrastructure-as-Code with change automation and support for scriptable admin tasks in any language, including Terraform
 * **Extensible** - A framework where everything can be extended to work the way you want to
 * **Comprehensive** - our [helm charts library](https://github.com/cloudposse/charts) are designed to tightly integrate your cloud-platform with Github Teams and Slack Notifications and CI/CD systems like TravisCI, CircleCI or Jenkins
 * **OpenSource** - Permissive [APACHE 2.0](LICENSE) license means no lock-in and no on-going license fees
 
-## Technologies
+## TECHNOLOGIES
 
 At its core, Geodesic is a framework for provisioning cloud infrastructure and the applications that sit on top of it. We leverage as many existing tools as possible to facilitate cloud fabrication and administration. We're like the connective tissue that sits between all of the components of a modern cloud.
 
@@ -27,6 +38,6 @@ At its core, Geodesic is a framework for provisioning cloud infrastructure and t
 
 [](https://media.giphy.com/media/26FmS6BRnPVPo2FDq/source.gif)
 
-## Documentation
+## SEE MORE
 
 Extensive documentation is provided on our [Documentation Hub](https://docs.cloudposse.com/geodesic). 
diff --git a/docs/design.md b/docs/design.md
@@ -1,6 +1,15 @@
-# Design
+---
+title: DESIGN(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
 
-## An Opinionated Framework
+## NAME
+
+design - Geodesic Design
+
+### An Opinionated Framework
 
 We designed this shell as the last layer of abstraction. It stitches all the tools together like `make`, `aws-cli`, `kops`, `helm`, `kubectl`, and `terraform`. As time progresses,
 there will undoubtably be even more that come into play. For this reason, we chose to use a combination of `bash` and `make` which together are ideally suited to combine the 
@@ -18,7 +27,7 @@ Since we use `make` under-the-hood, you can add all your ENVs at the end of the
 For the default environment variables, checkout `/etc/profile.d/defaults.sh`. We believe using ENVs this way is both consistent
 with the "cloud" (12-factor) way of doing things, as well as a clear way of communicating what values are being passed without using a complicated convention. Additionally, you can set & forget these ENVs in your shell.
 
-## Layout Inside the Shell
+## LAYOUT
 
 We leverage as many semantics of the linux shell as we can to make the experience as frictionless as possible.
 
@@ -27,23 +36,24 @@ We leverage as many semantics of the linux shell as we can to make the experienc
 * `/etc/bash_completion.d` is where all bash completion scripts are kept and sourced when the shell starts.
 * `/usr/local/bin` has some helper scripts
 * `/etc/motd` is the current "Message of the Day"
-* `/mnt/local` is where we house the local state (like your temporary AWS credentials)
-* `/mnt/remote` is where we mount the S3 bucket for cluster state; these files are never written to disk and only kept in memory for security
+* `/localhost` is where we house the local state (like your temporary AWS credentials). This is mounted to your `HOME` directory.
 * `/conf` is where all configurations belong. For example, stick your terraform module invocations in this directory. When using `terraform`, the directory names are mapped directly to a bucket prefix for terraform state which include subdirectories (e.g. `/conf/us-west-2/vpc` will map to a state folder prefix of `us-west-2/vpc`).
 
-## Extending the Shell
+## EXTENDING
 
 Geodesic was written to be easily extended. There are a couple ways to do it. 
 
 You can easily extend the Geodesic shell by creating your own repo with a `Dockerfile`. We suggest you have it inherit `FROM geodeisc:latest` (or pin it to a [build number](https://travis-ci.org/cloudposse/geodesic) for stability). If you want to add or modify core functionality, this is the recommended way to do it.
 
-In side your container, you can replace any of our code with your own to make it behave exactly as you wish. You could even create one dedicated shell per cluster with 
-logic tailored specifically for that cluster.
+In side your container, you can replace any of our code with your own to make it behave exactly as you wish. You could even create one dedicated shell per cluster with logic tailored specifically for that cluster.
+
+### Here are some other tips.
+
+1. Many of our `Makefiles` do an `-include Makefile.*`, which means, we'll include other `Makefiles` in that directory. To add additional functionality, simply drop-in your `Makefile.something` in that directory.
 
-Here are some other tips. Most of our modules do an `-include Makefile.*`, which means, we'll include other `Makefiles` in that directory. To add additional functionality,
-simply drop-in your `Makefile.something` in that module directory.
+2. Want to add additional aliases or affect the shell? Drop your script in `/etc/profile.d` and it will be loaded automatically when the shell starts. 
 
-Want to add additional aliases or affect the shell? Drop your script in `/etc/profile.d` and it will be loaded automatically when the shell starts. 
+3. Need to set some environment variables? Use an `.envrc` in the corresponding directory
 
 As you can see, you can easily change almost any aspect of how the shell works simply by extending it.
 
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,10 +1,21 @@
-# FAQ
+---
+title: FAQ(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
 
-## Does it work with Windows?
+## NAME
+
+FAQ - Frequently Asked Questions
+
+## QUESTIONS
+
+### Does it work with Windows?
 
 Yes! Geodesic runs on Windows 10, under the Windows Subsystem for Linux (WSL) for Ubuntu. 
 
-## Error: Cannot list directory
+### Error: Cannot list directory
 
 ```
 $ ls /s3
@@ -13,19 +24,20 @@ ls: reading directory '.': I/O error
 
 This means your AWS credentials have expired. Re-run `assume-role`.
 
-## Error: Cannot unmount folder
+### Error: Cannot unmount folder
+
 ```bash
 $ s3 unmount
 umount: can't unmount /s3: Resource busy
 ```
 
 This means some process (maybe you) is in the directory. Try running `cd /` and rerun the unmount.
 
-## What are the caveats?
+### What are the caveats?
 
 * While the underlying tools support multiple cloud providers, we are currently only testing with AWS. Pull Requests welcome.
 
-## Problems with `aws-vault`
+### Problems with `aws-vault`
 
 Most problems are related to environment settings. 
 
diff --git a/docs/kops.md b/docs/kops.md
@@ -1,4 +1,15 @@
-# Kubernetes Operations (kops)
+---
+title: KOPS(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
+
+## NAME
+
+kops - Kubernetes Operations (kops)
+
+## SYNOPSIS 
 
 Kops is one of the easiest ways to get a production grade Kubernetes cluster up and running. The `kops` command line tool (cli) is like `kubectl` for clusters. It handles all the standard CRUD operations necessary to manage the complete life cycle of a cluster.
 
@@ -7,7 +18,8 @@ current practice is to define one cluster per Geodesic contianer, with all clust
 in the `/conf` folder. We are planning to publish guidelines for how to manage multiple clusters per container, 
 but that is still a work in progress that will introduce some new patterns.
 
-### USAGE
+## DESCRIPTION
+
 - This document describes how to set up a single `kops` cluster in a single Geodesic container.
 - The described usage pattern corresponds to [Geodesic](https://github.com/cloudposse/geodesic) version 0.95.1,
 [Reference Architecture](https://github.com/cloudposse/reference-architectures) version 0.7.0, and
@@ -18,27 +30,7 @@ of its publication. Also, because it is only updated manually (rather than gener
 be times when one part of this document intends to reference one version of a resource while another part references 
 a different version. Please keep these facts in mind when you are using this document to help you set up your own cluster.
 
-## Table of Contents
-
-- [Kubernetes Operations (kops)](#kubernetes-operations-kops)
-  - [Usage](#usage)
-  - [Table of Contents](#table-of-contents)
-  - [Features](#features)
-  - [Overview](#overview)
-  - [Configuration Settings Overview](#configuration-settings-overview)
-    - [Terraform and Chamber](#terraform-and-chamber)
-    - [Where Did That Value Come From?](#where-did-that-value-come-from)
-  - [Create the Cluster](#create-the-cluster)
-    - [Setting the Parameters](#setting-the-parameters)
-    - [Shared VPC](#shared-vpc)
-    - [Provisioning Resrouces](#provisioning-resources)
-  - [Operating the Cluster](#operating-the-cluster)
-    - [Tips & Tricks](#tips--tricks)
-    - [Upgrade a Cluster](#upgrade-a-cluster)
-  - [References](#references)
-  - [Getting Help](#getting-help)
-
-## Features
+## FEATURES
 
 - **Automated Provisioning** of Kubernetes clusters in [AWS](https://github.com/kubernetes/kops/blob/master/docs/aws.md) and [GCE](https://github.com/kubernetes/kops/blob/master/docs/tutorial/gce.md)
 - **Highly Available (HA)** Kubernetes masters and nodes by using auto-scaling groups
@@ -50,7 +42,7 @@ a different version. Please keep these facts in mind when you are using this doc
 - **Supports Multiple CNIs** providers [out of the box](https://github.com/kubernetes/kops/blob/master/docs/networking.md).
 - **Lifecycle Hooks** make it easy to add containers and files to nodes via a [cluster manifest](https://github.com/kubernetes/kops/blob/master/docs/cluster_spec.md)
 
-## Overview
+## OVERVIEW
 
 The process of provisioning a new `kops` cluster takes (3) steps. Here's what it looks like:
 
@@ -68,7 +60,7 @@ The process of provisioning a new `kops` cluster takes (3) steps. Here's what it
    - Validate the cluster is healthy.
 
 
-## Configuration Settings Overview
+### Configuration Settings Overview
 
 We use 2 different mechanisms for storing configuration parameters.
 
@@ -114,7 +106,7 @@ Normally `direnv` only reads the `.envrc` file, but CloudPosse adds a `use envrc
 causes `direenv` to read all the files in the directory that have `.envrc` extensions. This allows parameters
 to be set automatically by `direnv` without requiring that the settings be put in a hidden file.
 
-##### `/conf/.direnv`
+##### `/conf/.envrc`
 
 In the `/conf` directory itself, we put a file named `.envrc` which contains just this one line:
 ```
@@ -196,7 +188,7 @@ SSM with the value from `kops.envrc`. This is why you should not set a parameter
 
 </details>
 
-## Create the cluster
+### Create the cluster
 
 The following describes how to create a cluster, treating the setting of parameters in various places as 
 steps in the creation process.
@@ -551,10 +543,10 @@ To upgrade the cluster or change settings (_e.g_. number of nodes, instance type
 8. Run `kops rolling-update cluster` to view a plan of changes
 9. Run `kops rolling-update cluster --yes --force` to force a rolling update (replace EC2 instances)
 
-## References
+## REFERENCES
 
 - https://github.com/kubernetes/kops/blob/master/docs/manifests_and_customizing_via_api.md
 
-## Getting Help
+## GETTING HELP
 
 Did you get stuck? Find us on [slack](https://slack.cloudposse.com) in the `#geodesic` channel.
diff --git a/docs/logo.md b/docs/logo.md
@@ -1,9 +1,22 @@
-## Our Logo
+---
+title: LOGO(1) | Geodesic
+author:
+- Erik Osterman
+date: May 2019
+---
+
+## NAME
+
+logo - Explanation of the Geodesic Logo
+
+## SYNOPSIS
 
 ![Geodesic Logo](https://raw.githubusercontent.com/cloudposse/geodesic/master/docs/geodesic-small.png)
 
 In mathematics, a geodesic line is the shortest distance between two points on a sphere. It's also a solid structure composed of geometric shapes such as hexagons.
 
+## DESCRIPTION
+
 We like to think of geodesic as the shortest path to a rock-solid cloud infrastructure. The geodesic logo is a hexagon with a cube suspended at its center. The cube represents this geodesic container, which is central to everything and at the same time is what ties everything together.
 
 But look a little closer and you’ll notice there’s much more to it. It's also an isometric shape of a cube with a missing piece. This represents its pluggable design, which lets anyone extend it to suit their vision.
diff --git a/geodesic_apkindex.md5 b/geodesic_apkindex.md5
@@ -1 +0,0 @@
-77e3cde7afac220dbf00e433fbaf4abb
diff --git a/packages.txt b/packages.txt
@@ -41,11 +41,13 @@ less
 libc6-compat
 libltdl
 make
+man-db@testing
 musl-dev
 ncurses
 oath-toolkit-oathtool@community
 openssh-client
 openssl
+pandoc@cloudposse
 pwgen
 python
 rakkess@cloudposse
diff --git a/rootfs/etc/profile.d/help.sh b/rootfs/etc/profile.d/help.sh
@@ -1,11 +1,8 @@
+# Use `man` page system for help
 function help() {
-	cat <<__EOF__
-Available commands:
-  leave-role      Leave the current role; run this to release your session
-  assume-role     Assume a new role; run this to renew your session
-  setup-role      Setup a new role; run this to configure your AWS profile
-  s3              Manage s3 buckets with fstab
-  init-terraform  Configure terraform project backend to use S3
-
-__EOF__
+	if [ $# -ne 0 ]; then
+		docs search --query="$*"
+	else
+		docs search
+	fi
 }
diff --git a/rootfs/usr/local/bin/docs b/rootfs/usr/local/bin/docs
