Generate live project documentation using mkdocs and gh-pages

.gitignore

@@ -81,3 +81,7 @@ default.etcd
 
 # Ignore awesome_bot markdown links check output
 ab-results-*.json
+
+# Ignore documentation site
+site
+

Makefile

@@ -711,3 +711,14 @@ bazel-version-dist: bazel-crossbuild-nodeup bazel-crossbuild-kops bazel-protokub
 .PHONY: bazel-upload
 bazel-upload: bazel-version-dist # Upload kops to S3
 	aws s3 sync --acl public-read ${BAZELUPLOAD}/ ${S3_BUCKET}
+
+#-----------------------------------------------------------  
+# static html documentation  
+
+.PHONY: live-docs
+live-docs:
+	@docker run --rm -it -p 3000:3000 -v ${PWD}:/docs aledbf/mkdocs:0.1
+
+.PHONY: build-docs
+build-docs:
+	@docker run --rm -it -v ${PWD}:/docs aledbf/mkdocs:0.1 build

docs/.pages

@@ -0,0 +1,10 @@
+arrange:
+- index.md
+- advisories
+- api-server
+- cli
+- development
+- examples
+- tutorial
+- releases
+- aws.md

docs/README.md

@@ -112,4 +112,3 @@
 * [Our release process](development/release.md)
 * [Releasing with Homebrew](development/homebrew.md)
 * [Rolling Update Diagrams](development/rolling_update.md)
-* [Updating Go Dependencies](development/dependencies.md)

docs/extra.css

@@ -0,0 +1,9 @@
+.md-typeset__table {
+    min-width: 100%;
+}
+
+@media only screen and (min-width: 768px){
+	td:nth-child(1){
+		white-space: nowrap;
+	}
+}

docs/index.md

@@ -0,0 +1,80 @@
+# kops - Kubernetes Operations
+
+[GoDoc]: https://godoc.org/k8s.io/kops
+[GoDoc Widget]: https://godoc.org/k8s.io/kops?status.svg
+
+The easiest way to get a production grade Kubernetes cluster up and running.
+
+## What is kops?
+
+We like to think of it as `kubectl` for clusters.
+
+`kops` helps you create, destroy, upgrade and maintain production-grade, highly
+available, Kubernetes clusters from the command line. AWS (Amazon Web Services)
+is currently officially supported, with GCE in beta support , and VMware vSphere
+in alpha, and other platforms planned.
+
+
+## Can I see it in action?
+
+<p align="center">
+  <a href="https://asciinema.org/a/97298">
+  <img src="https://asciinema.org/a/97298.png" width="885"></image>
+  </a>
+</p>
+
+
+## Features
+
+* Automates the provisioning of Kubernetes clusters in [AWS](aws.md) and [GCE](tutorial/gce.md)
+* Deploys Highly Available (HA) Kubernetes Masters
+* Built on a state-sync model for **dry-runs** and automatic **idempotency**
+* Ability to generate [Terraform](terraform.md)
+* Supports custom Kubernetes [add-ons](addons.md)
+* Command line [autocompletion](cli/kops_completion.md)
+* YAML Manifest Based API [Configuration](manifests_and_customizing_via_api.md)
+* [Templating](cluster_template.md) and dry-run modes for creating
+ Manifests
+* Choose from eight different CNI [Networking](networking.md) providers out-of-the-box
+* Supports upgrading from [kube-up](upgrade_from_kubeup.md)
+* Capability to add containers, as hooks, and files to nodes via a [cluster manifest](cluster_spec.md)
+
+
+## Documentation
+
+[To check out Live documentation](https://kubernetes.github.io/kops/)
+
+
+## Kubernetes Release Compatibility
+
+
+### Kubernetes Version Support
+
+kops is intended to be backward compatible.  It is always recommended to use the
+latest version of kops with whatever version of Kubernetes you are using.  Always
+use the latest version of kops.
+
+One exception, in regards to compatibility, kops supports the equivalent
+Kubernetes minor release number.  A minor version is the second digit in the
+release number.  kops version 1.8.0 has a minor version of 8. The numbering
+follows the semantic versioning specification, MAJOR.MINOR.PATCH.
+
+For example, kops 1.8.0 does not support Kubernetes 1.9.2, but kops 1.9.0
+supports Kubernetes 1.9.2 and previous Kubernetes versions. Only when kops minor
+version matches, the Kubernetes minor version does kops officially support the
+Kubernetes release.  kops does not stop a user from installing mismatching
+versions of K8s, but Kubernetes releases always require kops to install specific
+versions of components like docker, that tested against the particular
+Kubernetes version.
+
+#### Compatibility Matrix
+
+| kops version | k8s 1.5.x | k8s 1.6.x | k8s 1.7.x | k8s 1.8.x | k8s 1.9.x |
+|--------------|-----------|-----------|-----------|-----------|-----------|
+| 1.9.x        | Y         | Y         | Y         | Y         | Y         |
+| 1.8.x        | Y         | Y         | Y         | Y         | N         |
+| 1.7.x        | Y         | Y         | Y         | N         | N         |
+| 1.6.x        | Y         | Y         | N         | N         | N         |
+
+Use the latest version of kops for all releases of Kubernetes, with the caveat
+that higher versions of Kubernetes are not _officially_ supported by kops.

docs/releases/legacy-changes.md

@@ -13,7 +13,7 @@ Reworked SSH keys and support for running CI builds
 
 * Builds that are not published as Docker images can be run.  `kops` will pass a list of images in the NodeUp
   configuration, and NodeUp will download and `docker load` these images.  For examples, see the
-  [testing tips](docs/testing.md)
+  [testing tips](../development/testing.md)
 
 ## Jul 21 2016
 

hack/publish-docs.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Copyright 2018 The Kubernetes Authors.
+#
+# 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.
+
+if ! [ -z $DEBUG ]; then
+  set -x
+fi
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+if [ "$COMPONENT" != "docs" ]; then
+    echo "This task runs only to publish docs"
+    exit 0
+fi
+
+make -C ${DIR}/.. build-docs
+
+git config --global user.email "[email protected]"
+git config --global user.name "Travis Bot"
+
+git clone --branch=gh-pages --depth=1 https://${GH_REF} ${DIR}/gh-pages
+cd ${DIR}/gh-pages
+
+git rm -r .
+
+cp -r ${DIR}/../site/* .
+
+git add .
+git commit -m "Deploy GitHub Pages"
+git push --force --quiet "https://${GH_TOKEN}@${GH_REF}" gh-pages > /dev/null 2>&1

mkdocs.yml

@@ -0,0 +1,26 @@
+site_name: Kubernetes Operations - kops
+strict: true
+repo_name: 'kubernetes/kops'
+repo_url: 'https://github.com/kubernetes/kops'
+markdown_extensions:
+  - admonition
+  - codehilite
+  - pymdownx.inlinehilite
+  - pymdownx.tasklist(custom_checkbox=true)
+  - toc:
+      permalink: true
+theme:
+  name: material
+  feature:
+    tabs: true
+  logo:
+    icon: 'public'   # globe icon
+  palette:
+    primary: 'teal'
+    accent: 'green'
+plugins:
+  - search
+  - awesome-pages:
+      collapse_single_pages: true
+extra_css: [extra.css]
+#google_analytics: ['UA-XXXXXXX-X', 'kubernetes.github.io']

requirements-docs.txt

@@ -0,0 +1,5 @@
+mkdocs-material~=2.7.0
+mkdocs-awesome-pages-plugin~=1.2.0
+mkdocs~=0.17.0
+pygments~=2.2.0
+pymdown-extensions~=4.10