Documentation Site Framework (#1924)

* Initial doc site

* Make build happy

* Fix link

* Add missing boilerplate header

Our original boilerplate checker used regex and was incorrectly ignoring
this file. Now that I've fixed the grep call, this file is being picked
up in my PR.

* Do not validate bundler deps from docsite

Makefile

@@ -130,7 +130,7 @@ $(BINDIR)/user-broker: .init contrib/cmd/user-broker \
 
 .PHONY: $(BINDIR)/service-catalog
 service-catalog: $(BINDIR)/service-catalog
-$(BINDIR)/service-catalog: .init .generate_files cmd/service-catalog 
+$(BINDIR)/service-catalog: .init .generate_files cmd/service-catalog
 	$(DOCKER_CMD) $(GO_BUILD) -o $@ $(SC_PKG)/cmd/service-catalog
 
 # This section contains the code generation stuff
@@ -214,7 +214,7 @@ verify: .init verify-generated verify-client-gen verify-docs verify-vendor
 	@#
 	$(DOCKER_CMD) go vet $(SC_PKG)/...
 	@echo Running repo-infra verify scripts
-	@$(DOCKER_CMD) vendor/github.com/kubernetes/repo-infra/verify/verify-boilerplate.sh --rootdir=. | grep -v generated | grep -v .pkg > .out 2>&1 || true
+	@$(DOCKER_CMD) vendor/github.com/kubernetes/repo-infra/verify/verify-boilerplate.sh --rootdir=. | grep -Fv -e generated -e .pkg -e docsite > .out 2>&1 || true
 	@[ ! -s .out ] || (cat .out && rm .out && false)
 	@rm .out
 	@#
@@ -223,9 +223,9 @@ verify: .init verify-generated verify-client-gen verify-docs verify-vendor
 	@echo Running tag verification:
 	@$(DOCKER_CMD) build/verify-tags.sh
 
-verify-docs: .init
+verify-docs: .init docs
 	@echo Running href checker$(SKIP_COMMENT):
-	@$(DOCKER_CMD) verify-links.sh -s .pkg -t $(SKIP_HTTP) .
+	@$(DOCKER_CMD) verify-links.sh -s .pkg -s .bundler -s _plugins -s _includes -t $(SKIP_HTTP) .
 
 verify-generated: .init .generate_exes
 	$(DOCKER_CMD) $(BUILD_DIR)/update-apiserver-gen.sh --verify-only
@@ -414,3 +414,10 @@ verify-vendor: .init
 test-dep: .init
 	# Test that a downstream consumer of our client library can use dep
 	$(DOCKER_CMD) test/test-dep.sh
+
+.PHONY: docs
+docs:
+	./build/docs.sh generate
+
+docs-preview:
+	./build/docs.sh preview

build/docs.sh

@@ -0,0 +1,54 @@
+#!/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.
+
+set -xeuo pipefail
+
+REPO_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"
+DOCSITE=$REPO_ROOT/docsite
+DEST=$DOCSITE/_site
+
+clean() {
+  # Start fresh so that removed files are picked up
+  if [[ -d $DEST ]]; then
+    rm -r $DEST
+  fi
+  mkdir -p $DEST
+}
+
+# Serve a live preview of the site
+preview() {
+  clean
+
+  docker run -it --rm \
+    -v $DOCSITE:/srv/jekyll \
+    -v $REPO_ROOT/docs:/srv/docs \
+    -v $DOCSITE/.bundler:/usr/local/bundle \
+    -p 4000:4000 jekyll/jekyll jekyll serve
+}
+
+# Generate the static site's content
+generate() {
+  clean
+
+  echo "Generating site..."
+  docker run -it --rm \
+    -v $DOCSITE:/srv/jekyll \
+    -v $REPO_ROOT/docs:/srv/docs \
+    -v $DOCSITE/.bundler:/usr/local/bundle \
+    jekyll/jekyll jekyll build
+}
+
+"$@"

build/verify-errexit.sh

@@ -33,7 +33,7 @@ fi
 
 # Gather the list of files that appear to be shell scripts.
 # Meaning they have some form of "#!...sh" as a line in them.
-shFiles=$(grep -rl '^#!.*sh$' $args | grep -v ^pkg/kubernetes/)
+shFiles=$(grep -rl '^#!.*sh$' $args | grep -v ^pkg/kubernetes/ | grep -v .bundler)
 
 tmp=/tmp/out$RANDOM
 for file in ${shFiles}; do

docs/README.md

@@ -1,4 +1,9 @@
-# Service Catalog docs
+---
+title: Documentation
+layout: docsportal
+cid: docs-home
+permalink: /docs/
+---
 
 Welcome to the documentation for Service Catalog. This page is an index for
 the articles in here. We recommend you start by reading the 

docs/auth.md

@@ -1,4 +1,7 @@
-# Serving Certificates, Authentication, and Authorization
+---
+title: Serving Certificates, Authentication, and Authorization
+layout: docwithnav
+---
 
 This document outlines how the service catalog API server handles
 authentication and authorization.

docs/cli.md

@@ -1,4 +1,7 @@
-# Service Catalog CLI
+---
+title: CLI
+layout: docwithnav
+---
 
 This is a command-line interface (CLI) for interacting with Service Catalog
 resources. svcat is a domain-specific tool to make interacting with the Service Catalog easier.
@@ -30,7 +33,7 @@ when running in plugin mode, so instead of using `--flag` you must specify a val
 
 Run `svcat --help` to see the available commands.
 
-Below are some common tasks made easy with svcat. The example output assumes that the 
+Below are some common tasks made easy with svcat. The example output assumes that the
 [User Provided Service Broker](../charts/ups-broker) is installed on the cluster.
 
 * [Find brokers installed on the cluster](#find-brokers-installed-on-the-cluster)
@@ -142,7 +145,7 @@ $ svcat describe plan user-provided-service/default
     Status:        Active
     Free:          true
     Class:         user-provided-service
-  
+
   Instances:
         NAME       NAMESPACE   STATUS
   +--------------+-----------+--------+
@@ -187,7 +190,7 @@ $ svcat describe instance -n test-ns ups-instance
     Status:      Ready - The instance was provisioned successfully @ 2018-03-02 16:24:55 +0000 UTC
     Class:       user-provided-service
     Plan:        default
-  
+
   Bindings:
        NAME       STATUS
   +-------------+--------+

docs/code-standards.md

@@ -1,4 +1,7 @@
-# Code & Documentation Standards
+---
+title: Code & Documentation Standards
+layout: docwithnav
+---
 
 This document details our goals for code quality, coverage and documentation standards. At the time
 of this writing, these are standards that all of our code may not meet. We should always try to 

docs/concepts/index.md

@@ -0,0 +1,14 @@
+---
+title: Concepts
+layout: docwithnav
+---
+
+The Concepts section helps you learn about the parts of the Service Catalog system.
+
+## Overview
+
+TODO
+
+## Service Catalog Resources
+
+TODO

docs/concepts/service-catalog.md

@@ -0,0 +1,24 @@
+---
+title: What is Service Catalog?
+layout: docwithnav
+---
+
+{% capture overview %}
+This page is an overview of Service Catalog.
+{% endcapture %}
+
+{% capture body %}
+Service Catalog is awesome! 
+
+#### Why would I want Service Catalog on my cluster?
+
+Because it's awesome?
+
+{% endcapture %}
+
+{% capture whatsnext %}
+*   Ready to [Get Started](../walkthrough.md)?
+*   For more details, see the [Service Catalog Documentation](../README.md).
+{% endcapture %}
+{% include templates/concept.md %}
+

docs/contribute/docs.md

@@ -0,0 +1,10 @@
+---
+title: Contribute to our Docs
+layout: docwithnav
+---
+
+1. Clone this repository
+1. Run `make docs-preview`
+1. Navigate to [http://localhost:4000](http://localhost:4000) to view the site.
+1. Make changes to the files in /docs and reload the web page to view the 
+   changes (changes take about 4 seconds to be rebuilt).

docs/design.md

@@ -1,4 +1,7 @@
-# Design of the Service Catalog
+---
+title: Design of the Service Catalog
+layout: docwithnav
+---
 
 This document covers the architecture and design of Service Catalog.
 

docs/devguide.md

@@ -1,4 +1,7 @@
-# Developer's Guide to Service-Catalog
+---
+title: Developer's Guide
+layout: docwithnav
+---
 
 Table of Contents
 - [Overview](#overview)

docs/install.md

@@ -1,4 +1,7 @@
-# Installing Service Catalog
+---
+title: Install
+layout: docwithnav
+---
 
 Kubernetes 1.7 or higher clusters run the
 [API Aggregator](https://kubernetes.io/docs/concepts/api-extension/apiserver-aggregation/),

docs/introduction.md

@@ -1,4 +1,7 @@
-# Service Catalog Introduction
+---
+title: Introduction
+layout: docwithnav
+---
 
 The Kubernetes Service Catalog provides a Kubernetes-native interface to one
 or more [Open Service Broker API](https://www.openservicebrokerapi.org/)

docs/parameters.md

@@ -1,3 +1,8 @@
+---
+title: Parameters
+layout: docwithnav
+---
+
 # Passing parameters to brokers
 
 Table of Contents

docs/resources.md

@@ -1,4 +1,7 @@
-# Details on Service Catalog Resources
+---
+title: Resources
+layout: docwithnav
+---
 
 The Service Catalog resource model specifies all the behaviors that 
 Service Catalog supports. This document details each resource.

docs/walkthrough.md

@@ -1,4 +1,7 @@
-# Service Catalog Demonstration Walkthrough
+---
+title: Walkthrough
+layout: docwithnav
+---
 
 This document assumes that you've installed Service Catalog onto your cluster.
 If you haven't, please see [install.md](./install.md). Optionally you may install
@@ -8,6 +11,8 @@ so that you may follow this walkthrough using svcat or using only kubectl.
 All commands in this document assume that you're operating out of the root
 of this repository.
 
+<a id="install" />
+
 # Step 1 - Installing the UPS Broker Server
 
 Since the Service Catalog provides a Kubernetes-native interface to an 

docsite/.gitignore

@@ -0,0 +1,4 @@
+_site
+.bundler
+.sass-cache
+.jekyll-metadata

docsite/.ruby-version

@@ -0,0 +1 @@
+2.4.3

docsite/404.md

@@ -0,0 +1,11 @@
+---
+layout: docwithnav
+title: 404 Error!
+permalink: /404.html
+no_canonical: true
+sitemap: false
+---
+
+<script src="/js/redirects.js"></script>
+
+Sorry, this page was not found. :(

docsite/Gemfile

@@ -0,0 +1,53 @@
+source "https://rubygems.org"
+
+# gem "github-pages", group: :jekyll_plugins
+
+gem "jekyll", "3.6.0"
+
+group :github_pages_compatible do
+    gem "json", "~> 1.7", ">= 1.7.7"
+    gem "coffee-script", "~> 2.4"
+    gem "coffee-script-source", "~> 1.12"
+    gem "ethon", "~> 0.10"
+    gem "execjs", "~> 2.7"
+    gem "minima", "~> 2.0"
+    gem "terminal-table", "~> 1.4"
+    gem "unicode-display_width", "~> 1.1"
+end
+
+group :jekyll_plugins do
+   gem "jekyll-feed", "~> 0.6"
+   gem "jekyll-sitemap"
+   gem "jekyll-gist"
+   gem "jekyll-paginate", "1.1.0"
+   gem "jekyll-seo-tag"
+   gem "jekyll-avatar", "~> 0.4"
+   gem "jekyll-coffeescript", "~> 1.0"
+   gem "jekyll-default-layout", "~> 0.1"
+   gem "jekyll-github-metadata", "~> 2.2"
+   gem "jekyll-optional-front-matter", "~> 0.1"
+   gem "jekyll-readme-index", "0.0.3"
+   gem "jekyll-redirect-from", "~> 0.13"
+   gem "jekyll-relative-links", "~> 0.5.3"
+   gem "jekyll-swiss", "~> 0.4"
+   gem "jekyll-theme-architect", "0.0.3"
+   gem "jekyll-theme-cayman", "0.0.3"
+   gem "jekyll-theme-dinky", "0.0.3"
+   gem "jekyll-theme-hacker", "0.0.3"
+   gem "jekyll-theme-leap-day", "0.0.3"
+   gem "jekyll-theme-merlot", "0.0.3"
+   gem "jekyll-theme-midnight", "0.0.3"
+   gem "jekyll-theme-minimal", "0.0.3"
+   gem "jekyll-theme-modernist", "0.0.3"
+   gem "jekyll-theme-primer", "~> 0.1"
+   gem "jekyll-theme-slate", "0.0.3"
+   gem "jekyll-theme-tactile", "0.0.3"
+   gem "jekyll-theme-time-machine", "0.0.3"
+   gem "jekyll-titles-from-headings", "~> 0.1"
+   gem "jekyll-include-cache", "~> 0.1"
+   gem 'jekyll-youtube', '~> 1.0'
+end
+
+gem "kramdown", "~> 1.11"
+gem "rouge", "~> 2.0"
+gem "pry"