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

Munge headerlines

Author: davidopp

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
+}

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))
+		}
+	}
+}

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},

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

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

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.

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**

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.

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"}`

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: