Merge pull request kubernetes#11452 from thockin/docs-munge-headerlines

Munge headerlines
lavalamp · Jul 17, 2015 · d28a665 · d28a665
2 parents ce6b137 + 33f1862
commit d28a665
Show file tree

Hide file tree

Showing 214 changed files with 745 additions and 29 deletions.
diff --git a/cmd/mungedocs/headers.go b/cmd/mungedocs/headers.go
@@ -0,0 +1,71 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+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.
+*/
+
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var headerRegex = regexp.MustCompile(`^(#+)\s*(.*)$`)
+var whitespaceRegex = regexp.MustCompile(`^\s*$`)
+
+func fixHeaderLines(fileBytes []byte) []byte {
+	lines := splitLines(fileBytes)
+	out := []string{}
+	for i := range lines {
+		matches := headerRegex.FindStringSubmatch(lines[i])
+		if matches == nil {
+			out = append(out, lines[i])
+			continue
+		}
+		if i > 0 && !whitespaceRegex.Match([]byte(out[len(out)-1])) {
+			out = append(out, "")
+		}
+		out = append(out, fmt.Sprintf("%s %s", matches[1], matches[2]))
+		if i+1 < len(lines) && !whitespaceRegex.Match([]byte(lines[i+1])) {
+			out = append(out, "")
+		}
+	}
+	final := strings.Join(out, "\n")
+	// Preserve the end of the file.
+	if len(fileBytes) > 0 && fileBytes[len(fileBytes)-1] == '\n' {
+		final += "\n"
+	}
+	return []byte(final)
+}
+
+// Header lines need whitespace around them and after the #s.
+func checkHeaderLines(filePath string, fileBytes []byte) ([]byte, error) {
+	fbs := splitByPreformatted(fileBytes)
+	fbs = append([]fileBlock{{false, []byte{}}}, fbs...)
+	fbs = append(fbs, fileBlock{false, []byte{}})
+
+	for i := range fbs {
+		block := &fbs[i]
+		if block.preformatted {
+			continue
+		}
+		block.data = fixHeaderLines(block.data)
+	}
+	output := []byte{}
+	for _, block := range fbs {
+		output = append(output, block.data...)
+	}
+	return output, nil
+}
diff --git a/cmd/mungedocs/headers_test.go b/cmd/mungedocs/headers_test.go
@@ -0,0 +1,71 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+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.
+*/
+
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHeaderLines(t *testing.T) {
+	var cases = []struct {
+		in  string
+		out string
+	}{
+		{"", ""},
+		{
+			"# ok",
+			"# ok",
+		},
+		{
+			"## ok",
+			"## ok",
+		},
+		{
+			"##### ok",
+			"##### ok",
+		},
+		{
+			"##fix",
+			"## fix",
+		},
+		{
+			"foo\n\n##fix\n\nbar",
+			"foo\n\n## fix\n\nbar",
+		},
+		{
+			"foo\n##fix\nbar",
+			"foo\n\n## fix\n\nbar",
+		},
+		{
+			"foo\n```\n##fix\n```\nbar",
+			"foo\n```\n##fix\n```\nbar",
+		},
+		{
+			"foo\n#fix1\n##fix2\nbar",
+			"foo\n\n# fix1\n\n## fix2\n\nbar",
+		},
+	}
+	for i, c := range cases {
+		actual, err := checkHeaderLines("filename.md", []byte(c.in))
+		assert.NoError(t, err)
+		if string(actual) != c.out {
+			t.Errorf("case[%d]: expected %q got %q", i, c.out, string(actual))
+		}
+	}
+}
diff --git a/cmd/mungedocs/mungedocs.go b/cmd/mungedocs/mungedocs.go
@@ -48,6 +48,7 @@ Examples:
 		{"table-of-contents", updateTOC},
 		{"check-links", checkLinks},
 		{"blank-lines-surround-preformatted", checkPreformatted},
+		{"header-lines", checkHeaderLines},
 		{"unversioned-warning", updateUnversionedWarning},
 		{"analytics", checkAnalytics},
 		{"kubectl-dash-f", checkKubectlFileTargets},

diff --git a/docs/README.md b/docs/README.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Kubernetes Documentation: releases.k8s.io/HEAD
 
 * The [User's guide](user-guide/README.md) is for anyone who wants to run programs and

diff --git a/docs/admin/README.md b/docs/admin/README.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Kubernetes Cluster Admin Guide
 
 The cluster admin guide is for anyone creating or administering a Kubernetes cluster.
@@ -72,6 +73,7 @@ If you are modifying an existing guide which uses Salt, this document explains [
 project.](salt.md).
 
 ## Upgrading a cluster
+
 [Upgrading a cluster](cluster-management.md).
 
 ## Managing nodes

diff --git a/docs/admin/accessing-the-api.md b/docs/admin/accessing-the-api.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Configuring APIserver ports
 
 This document describes what ports the kubernetes apiserver
@@ -42,6 +43,7 @@ in [Accessing the cluster](../user-guide/accessing-the-cluster.md).
 
 
 ## Ports and IPs Served On
+
 The Kubernetes API is served by the Kubernetes APIServer process.  Typically,
 there is one of these running on a single kubernetes-master node.
 
@@ -93,6 +95,7 @@ variety of uses cases:
       setup time. Kubelets use cert-based auth, while kube-proxy uses token-based auth.
 
 ## Expected changes
+
    - Policy will limit the actions kubelets can do via the authed port.
    - Scheduler and Controller-manager will use the Secure Port too.  They
      will then be able to run on different machines than the apiserver.

diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Admission Controllers
 
 **Table of Contents**

diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Authentication Plugins
 
 Kubernetes uses client certificates, tokens, or http basic auth to authenticate users for API calls.

diff --git a/docs/admin/authorization.md b/docs/admin/authorization.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Authorization Plugins
 
 
@@ -53,6 +54,7 @@ The following implementations are available, and are selected by flag:
 `ABAC` allows for user-configured authorization policy.  ABAC stands for Attribute-Based Access Control.
 
 ## ABAC Mode
+
 ### Request Attributes
 
 A request has 4 attributes that can be considered for authorization:
@@ -105,6 +107,7 @@ To permit any user to do something, write a policy with the user property unset.
 To permit an action Policy with an unset namespace applies regardless of namespace.
 
 ### Examples
+
  1. Alice can do anything: `{"user":"alice"}`
  2. Kubelet can read any pods: `{"user":"kubelet", "resource": "pods", "readonly": true}`
  3. Kubelet can read and write events: `{"user":"kubelet", "resource": "events"}`

diff --git a/docs/admin/cluster-components.md b/docs/admin/cluster-components.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Kubernetes Cluster Admin Guide: Cluster Components
 
 This document outlines the various binary components that need to run to
@@ -92,6 +93,7 @@ These controllers include:
 selects a node for them to run on.
 
 ### addons
+
 Addons are pods and services that implement cluster features. They don't run on
 the master VM, but currently the default setup scripts that make the API calls
 to create these pods and services does run on the master VM. See:

diff --git a/docs/admin/cluster-large.md b/docs/admin/cluster-large.md
@@ -30,9 +30,11 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Kubernetes Large Cluster
 
 ## Support
+
 At v1.0, Kubernetes supports clusters up to 100 nodes with 30 pods per node and 1-2 container per pod (as defined in the [1.0 roadmap](../../docs/roadmap.md#reliability-and-performance)).
 
 ## Setup
@@ -59,6 +61,7 @@ To avoid running into cloud provider quota issues, when creating a cluster with
 * Gating the setup script so that it brings up new node VMs in smaller batches with waits in between, because some cloud providers rate limit the creation of VMs.
 
 ### Addon Resources
+
 To prevent memory leaks or other resource issues in [cluster addons](../../cluster/addons/) from consuming all the resources available on a node, Kubernetes sets resource limits on addon containers to limit the CPU and Memory resources they can consume (See PR [#10653](https://github.com/GoogleCloudPlatform/kubernetes/pull/10653/files) and [#10778](https://github.com/GoogleCloudPlatform/kubernetes/pull/10778/files)).
 
 For example:

diff --git a/docs/admin/cluster-management.md b/docs/admin/cluster-management.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Cluster Management
 
 This doc is in progress.

diff --git a/docs/admin/cluster-troubleshooting.md b/docs/admin/cluster-troubleshooting.md
@@ -30,13 +30,16 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # Cluster Troubleshooting
+
 This doc is about cluster troubleshooting; we assume you have already ruled out your application as the root cause of the
 problem you are experiencing. See
 the [application troubleshooting guide](../user-guide/application-troubleshooting.md) for tips on application debugging.
 You may also visit [troubleshooting document](../troubleshooting.md) for more information. 
 
 ## Listing your cluster
+
 The first thing to debug in your cluster is if your nodes are all registered correctly.
 
 Run
@@ -48,15 +51,18 @@ kubectl get nodes
 And verify that all of the nodes you expect to see are present and that they are all in the ```Ready``` state.
 
 ## Looking at logs
+
 For now, digging deeper into the cluster requires logging into the relevant machines.  Here are the locations
 of the relevant log files.  (note that on systemd-based systems, you may need to use ```journalctl``` instead)
 
 ### Master
+
    * /var/log/kube-apiserver.log - API Server, responsible for serving the API
    * /var/log/kube-scheduler.log - Scheduler, responsible for making scheduling decisions
    * /var/log/kube-controller-manager.log - Controller that manages replication controllers
 
 ### Worker Nodes
+
    * /var/log/kubelet.log - Kubelet, responsible for running containers on the node
    * /var/log/kube-proxy.log - Kube Proxy, responsible for service load balancing
 

diff --git a/docs/admin/dns.md b/docs/admin/dns.md
@@ -30,6 +30,7 @@ Documentation for other releases can be found at
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
+
 # DNS Integration with Kubernetes
 
 As of kubernetes 0.8, DNS is offered as a [cluster add-on](../../cluster/addons/README.md).