Add prototype documentation site (#514)

* Add prototype documentation site

- developed with Hugo, though the design is currently quite minimal
  as I am not focusing on those parts right now
- imported User Guide (install docs still will live in the repo README)
- imported Developer Guide and made some heavy editing, added new pages

I recommend we merge this as-is and continue iterating on it over time.

To try this patch out: cd site; hugo serve

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

* Apply suggestions from code review

Code review suggestions.

Co-Authored-By: Cornelius Weig <22861411+corneliusweig@users.noreply.github.com>

* Address more code review feedback

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

Co-authored-by: Cornelius Weig <22861411+corneliusweig@users.noreply.github.com>

site/.gitignore

@@ -0,0 +1,2 @@
+public/
+resources/

site/config.yaml

@@ -0,0 +1,7 @@
+baseURL: "https://krew.sigs.k8s.io/"
+languageCode: "en-us"
+title: "Krew – kubectl plugin manager"
+
+markup:
+    highlight:
+      style: dracula

site/content/docs/_index.md

@@ -0,0 +1,3 @@
+---
+title: Krew
+---

site/content/docs/developer-guide/_index.md

@@ -0,0 +1,4 @@
+---
+title: Developer Guide
+weight: 300
+---

site/content/docs/developer-guide/develop/_index.md

@@ -0,0 +1,4 @@
+---
+title: Developing kubectl plugins
+weight: 100
+---

site/content/docs/developer-guide/develop/best-practices.md

@@ -0,0 +1,55 @@
+---
+title: Best practices
+slug: best-practices
+weight: 300
+---
+
+This guide lists practices to use while developing `kubectl` plugins. Before
+submitting your plugin to Krew, please review these
+
+While Krew project does not enforce any strict guidelines about how a plugin
+works, using some of these practices can help your plugin work for more users
+and behave more predictably.
+
+### Choosing a language
+
+Most `kubectl` plugins are written in Go or as bash scripts.
+
+If you are planning to write a plugin with Go, check out:
+
+- [client-go]: a Go SDK to work with Kubernetes API and kubeconfig files
+- [cli-runtime]: Provides packages to share code with `kubectl` for printing output or [sharing command-line options][cli-opts]
+- [sample-cli-plugin]: An example plugin implementation in Go
+
+### Consistency with kubectl
+
+Krew does not try to impose any rules in terms of the shape of your plugin.
+
+However, if you use the command-line options with `kubectl`, you can make your
+users’ lives easier.
+
+For example, it is recommended you use the following command line flags used by
+`kubectl`:
+
+- `-h`/`--help`
+- `-n`/`--namespace`
+- `-A`/`--all-namespaces`
+
+Furthermore, by using the [genericclioptions][cli-opts] package (Go), you can
+support the global command-line flags listed in `kubectl options` (e.g.
+`--kubeconfig`, `--context` and many others) in your plugins.
+
+### Import authentication plugins (Go)
+
+By default, plugins that use [client-go]
+cannot authenticate to Kubernetes clusters on many cloud providers. To overcome
+this, add the following import to somewhere in your binary:
+
+```go
+import _ "k8s.io/client-go/plugin/pkg/client/auth"
+```
+
+[cli-runtime]: https://github.com/kubernetes/cli-runtime/
+[client-go]: https://godoc.org/k8s.io/client-go
+[cli-opts]: https://godoc.org/k8s.io/cli-runtime/pkg/genericclioptions
+[sample-cli-plugin]: https://github.com/kubernetes/sample-cli-plugin

site/content/docs/developer-guide/develop/naming-guide.md

@@ -0,0 +1,84 @@
+---
+title: Plugin Naming Guide
+slug: naming-guide
+weight: 200
+---
+
+This document explains the best practices and recommendations for naming your
+kubectl plugins.
+
+These guidelines are used for reviewing the plugins [submitted to Krew]({{<ref
+"../release/submitting-to-krew.md">}}).
+
+##### _Punctuation_
+
+Plugin names must be all lowercase and separate words with hyphens.
+**Don't** use camelCase, PascalCase, or snake_case; use
+[kebab-case](http://wiki.c2.com/?KebabCase).
+
+- **DON'T:** `kubectl OpenSvc`
+- **DO:** `kubectl open-svc`
+
+##### _Be specific_
+
+Plugin names should not be verbs/nouns that are generic, already overloaded, or
+possibly can be used for broader purposes by another plugin.
+
+- **DON'T:** `kubectl login`: Tries to put dibs on the word.
+- **DO:** `kubectl gke-login`.
+
+Also:
+
+- **DON'T:** `kubectl ui`: Should be used only for Kubernetes Dashboard.
+- **DO:** `kubectl gke-ui`.
+
+##### _Be unique_
+
+Try to find a unique name for your plugin that differentiates you from other
+possible plugins doing the same job.
+
+- **DON'T:** `kubectl view-logs`: Unclear how it is different than the builtin
+  "logs" command, or many other tools for viewing logs.
+- **DO:** `kubectl tailer`:  Unique name, points to the underlying
+  tool name.
+
+##### _Use Verbs/Resource Types_
+
+If the name does not make it clear (a) what verb the plugin is doing on a
+resource, or (b) what kind of resource it's doing the action on, consider
+clarifying unless it is obvious.
+
+- **DON'T:** `kubectl service`: Unclear what this plugin is doing with
+  service.
+- **DON'T:** `kubectl open`: Unclear what it is opening.
+- **DO:** `kubectl open-svc`: It is clear the plugin will open a service.
+
+##### _Prefix Vendor Identifiers_
+
+Use the vendor-specific strings as prefix, separated with a dash. This makes it
+easier to search/group plugins that are about a specific vendor.
+
+- **DON'T:** `kubectl ui-gke`: Makes it harder to search or locate in a
+  plugin list.
+- **DO:** `kubectl gke-ui`: Will show up next to other gke-* plugins.
+
+##### _Avoid repeating kube[rnetes]_
+
+Plugin names should not repeat kube- or kubernetes- prefixes to avoid
+stuttering.
+
+- **DON'T:** `kubectl kube-node-admin`: "kubectl " already has "kube" in
+  it.
+- **DO:** `kubectl node-admin`.
+
+##### _Avoid Resource Acronyms_
+
+Using kubectl acronyms for API resources (e.g. svc, ing, deploy, cm) reduces
+readability and discoverability of a plugin more than it is saving keystrokes.
+
+- **DON'T:** `kubectl new-ing`: Hard to spot and the plugin is for
+  Ingress.
+- **DO:** `kubectl debug-ingress`.
+
+If you have suggestions to this guide, open an issue or send a pull request, as
+this is an open topic of debate with a lot of gray areas.

site/content/docs/developer-guide/develop/plugin-development.md

@@ -0,0 +1,41 @@
+---
+title: Introduction to plugin development
+weight: 100
+---
+
+If you are looking to start developing plugins for `kubectl`, read the
+[Kubernetes
+documentation](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/)
+on this topic.
+
+To summarize the documentation, the procedure is to:
+
+- Write an executable binary, named `kubectl-foo` to have a plugin that can be
+  invoked as `kubectl foo`.
+- Place the executable to a directory listed in user’s `PATH` environment
+  variable. (Plugins distributed with Krew don't need to worry  about this).
+- You can't overwrite a builtin `kubectl` command with a plugin.
+
+> **If you are writing a plugin in Go:** Consider using the [cli-runtime] project
+> which is designed to provide the same command-line arguments, kubeconfig
+> parser, Kubernetes API REST client, and printing logic. Look at
+> [sample-cli-plugin] for an example of a kubectl plugin.
+>
+> Also, there's an unofficial [GitHub template
+> repo](https://github.com/replicatedhq/krew-plugin-template) for a Krew plugin
+> in Go that implements some best practices mentioned in this guide, and helps
+> you automate releases using GoReleaser to create release when a tag is pushed.
+
+[cli-runtime]: https://github.com/kubernetes/cli-runtime/
+[sample-cli-plugin]: https://github.com/kubernetes/sample-cli-plugin
+
+While developing a plugin, make sure you check out:
+
+- [Plugin naming guide]({{<ref "naming-guide.md">}}) to choose a good name
+  for your plugin
+- [Plugin development best practices]({{<ref "best-practices.md">}}) guide
+  for a brief checklist of what we're looking for in the submitted plugins.
+
+After you develop a plugin with a good name following the best practices, you
+can [develop a Krew plugin manifest]({{<ref "../plugin-manifest.md">}}) and
+[submit your plugin to Krew]({{<ref "../release/submitting-to-krew.md">}}).

site/content/docs/developer-guide/example-plugin-manifests.md

@@ -0,0 +1,29 @@
+---
+title: Example plugin manifests
+slug: example-manifests
+weight: 200
+---
+
+Learning how to [write plugin manifests]({{< ref "plugin-manifest.md" >}})
+can be a time-consuming tasks.
+
+Krew encourages you to copy and adapt plugin manifests of [existing
+plugins][list]. Since these are already reviewed and approved, your plugin can
+be accepted more quickly.
+
+* **Go:**
+  - [tree](https://github.com/kubernetes-sigs/krew-index/blob/master/plugins/tree.yaml):
+    supports Windows/Linux/macOS, per-OS builds, extracts all files from the
+    archive
+  - [sort-manifests](https://github.com/kubernetes-sigs/krew-index/blob/master/plugins/sort-manifests.yaml):
+    Linux/macOS only, extracting specific files
+
+* **Bash:**
+  - [ctx](https://github.com/kubernetes-sigs/krew-index/blob/master/plugins/ctx.yaml):
+    Linux/macOS only, downloads GitHub tag tarball, extracts using wildcards
+
+* **Rust:**
+  - [view-allocations](https://github.com/kubernetes-sigs/krew-index/blob/master/plugins/view-allocations.yaml):
+    Linux/macOS only, implicitly extracts all files from the archive
+
+[list]: https://github.com/kubernetes-sigs/krew-index/tree/master/plugins

site/content/docs/developer-guide/installing-locally.md

@@ -0,0 +1,42 @@
+---
+title: Testing plugin installation locally
+slug: testing-locally
+weight: 300
+---
+
+After you have written your [plugin manifest]({{< ref "plugin-manifest.md" >}})
+archived your plugin into a `.zip` or `.tar.gz` file, you can now test whether
+your plugin installs correctly with Krew by running:
+
+```sh
+{{<prompt>}}kubectl krew install --manifest=foo.yaml --archive=foo.tar.gz
+```
+
+- `--manifest` flag specifies a custom manifest rather than picking it up from
+  the default [krew index][index]
+- `--archive` overrides the download `uri:` specified in the plugin manifest and
+  uses a local `.zip` or `.tar.gz` file instead.
+
+If the installation **fails**, run the command again with `-v=4` flag to see the
+verbose logs and inspect what went wrong.
+
+If your installation **succeeds**, you should now be able to run your plugin.
+
+If you made your archive file available to download on the Internet, run the
+same command without the `--archive` option and actually test downloading the
+file from the specified `uri` and validate its `sha256` sum is correct.
+
+After you have tested your plugin, uninstall it with `kubectl krew uninstall foo`.
+
+### Testing other platforms
+
+If you need other `platforms` definitions that don't match your current machine,
+you can use `KREW_OS` and/or `KREW_ARCH` environment variables to override what
+OS/architecture Krew thinks it's running on.
+
+For example, if you're on a Linux machine, you can test Windows installation
+with:
+
+```sh
+{{<prompt>}}KREW_OS=windows KREW_ARCH=amd64 krew install --manifest=[...]
+```