doc(Issue:1905):Improve doc titles in order to better be returned in the searches (#1928)

camilamacedo86 · web-flow · commit 491cdf6d9f60 · 2019-10-08T23:16:37.000+01:00
* doc(Issue:1905):Improve doc titles in order to better be returned in the searchs
diff --git a/doc/ansible/dev/advanced_options.md b/doc/ansible/dev/advanced_options.md
@@ -1,8 +1,8 @@
-## Advanced Options
+# Advanced Options for Operator SDK Ansible-based Operators
 
 This document shows the advanced options available to a developer of an ansible operator.
 
-### Watches File Options
+## Watches File Options
 
 The advanced features can be enabled by adding them to your watches file per GVK.
 They can go below the `group`, `version`, `kind` and `playbook` or `role`.
diff --git a/doc/ansible/dev/apb_migration_guide.md b/doc/ansible/dev/apb_migration_guide.md
@@ -1,4 +1,4 @@
-# Migrating an Ansible Playbook Bundle (APB) to an Ansible-based Operator
+# Migrating an Ansible Playbook Bundle (APB) to an Operator SDK Ansible-based Operator
 
 This guide will walk you through migrating your legacy Ansible Playbook Bundles (APB)
 to a more modern Kubernetes Operator architecture. We will cover how to prepare a new
diff --git a/doc/ansible/dev/dependent_watches.md b/doc/ansible/dev/dependent_watches.md
@@ -1,4 +1,4 @@
-# Dependent Watches
+# Dependent Watches in Operator SDK Ansible-based Operators
 This document describes the `watchDependentResources` option in [`watches.yaml`](#Example) file. It delves into what dependent resources are, why the option is required, how it is achieved and finally gives an example.
 
 ### What are dependent resources?
@@ -30,4 +30,4 @@ This is an example of a watches file with the `watchDependentResources` field se
   manageStatus: False
   watchDependentResources: True
 
-```
+```
diff --git a/doc/ansible/dev/finalizers.md b/doc/ansible/dev/finalizers.md
@@ -1,4 +1,4 @@
-# Handling deletion events
+# Handling Deletion Events with Operator SDK Ansible-based Operators
 
 The default behavior of an Ansible Operator is to delete all resources the operator
 created during reconciliation when a managed resource is marked for deletion. This
diff --git a/doc/ansible/dev/testing_guide.md b/doc/ansible/dev/testing_guide.md
@@ -1,4 +1,4 @@
-# Testing Ansible Operators with Molecule
+# Testing Operator SDK Ansible-based Operators with Molecule
 
 ## Getting started
 
diff --git a/doc/ansible/information-flow-ansible-operator.md b/doc/ansible/information-flow-ansible-operator.md
@@ -1,4 +1,4 @@
-# Information Flow for Ansible Operator
+# Information Flow for Operator SDK Ansible-based Operators
 
 ![Ansible Operator Flow](ao-flow.png)
 
diff --git a/doc/ansible/project_layout.md b/doc/ansible/project_layout.md
@@ -1,4 +1,4 @@
-# Project Scaffolding Layout
+# Project Scaffolding Layout for Operator SDK Ansible-based Operators
 
 After creating a new operator project using
 `operator-sdk new --type ansible`, the project directory has numerous generated folders and files. The following table describes a basic rundown of each generated file/directory.
diff --git a/doc/dev/release.md b/doc/dev/release.md
@@ -1,4 +1,4 @@
-# Releases
+# Operator SDK Release guide
 
 Making an Operator SDK release involves:
 
diff --git a/doc/dev/reporting_bugs.md b/doc/dev/reporting_bugs.md
@@ -1,4 +1,4 @@
-# Reporting bugs
+# Reporting bugs in Operator SDK
 
 If any part of the operator-sdk project has bugs or documentation mistakes, please let us know by [opening an issue][operator-sdk-issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.
 
diff --git a/doc/dev/testing/running-the-tests.md b/doc/dev/testing/running-the-tests.md
@@ -1,4 +1,4 @@
-# Running the SDK Tests
+# Running the Operator SDK Tests
 
 The operator-sdk is automatically tested with a variety of tests anytime
 a pull request is made. The E2E tests ensure that the operator-sdk acts as intended by
diff --git a/doc/dev/testing/travis-build.md b/doc/dev/testing/travis-build.md
@@ -1,4 +1,4 @@
-# TravisCI Build Information
+# TravisCI Build Information for Operator SDK
 
 Travis is set to run one every push to a branch or PR.
 The results of the builds can be found [here][branches] for branches and [here][pr-builds] for PRs.
diff --git a/doc/faq.md b/doc/faq.md
@@ -1,14 +1,14 @@
-# FAQ
+# Operator SDK FAQ
 
-### How can I have separate logic for Create, Update, and Delete events? When reconciling an object can I access its previous state?
+## How can I have separate logic for Create, Update, and Delete events? When reconciling an object can I access its previous state?
 
 You should not have separate logic. Instead design your reconciler to be idempotent. See the [controller-runtime FAQ][controller-runtime_faq] for more details.
 
-### When my Custom Resource is deleted, I need to know its contents or perform cleanup tasks. How can I do that?
+## When my Custom Resource is deleted, I need to know its contents or perform cleanup tasks. How can I do that?
 
 Use a [finalizer].
 
-### I keep seeing the following intermittent warning in my Operator's logs: `The resourceVersion for the provided watch is too old.` What's wrong?
+## I keep seeing the following intermittent warning in my Operator's logs: `The resourceVersion for the provided watch is too old.` What's wrong?
 
 This is completely normal and expected behavior.
 
@@ -21,7 +21,7 @@ Never seeing this warning may suggest that your watch or cache is not healthy. I
 For more information on `kube-apiserver` request timeout options, see the [Kubernetes API Server Command Line Tool Reference][kube-apiserver_options]
 
 
-### I keep seeing errors like "Failed to create metrics Service", how do I fix this?
+## I keep seeing errors like "Failed to create metrics Service", how do I fix this?
 
 If you run into the following error message:
 
diff --git a/doc/helm/dev/developer_guide.md b/doc/helm/dev/developer_guide.md
@@ -1,4 +1,4 @@
-# Developer guide
+# Helm Developer guide for Operator SDK
 
 This document provides some useful information and tips for a developer
 creating an operator powered by Helm.
diff --git a/doc/helm/project_layout.md b/doc/helm/project_layout.md
@@ -1,4 +1,4 @@
-# Project Scaffolding Layout
+# Project Scaffolding Layout for Operator SDK Helm-based Operators
 
 After creating a new operator project using `operator-sdk new --type helm`,
 the project directory has numerous generated folders and files. The following
diff --git a/doc/migration/v0.1.0-migration-guide.md b/doc/migration/v0.1.0-migration-guide.md
@@ -1,4 +1,4 @@
-# Migration Guide from v0.0.x to v0.1.0
+# Operator SDK Migration Guide from v0.0.x to v0.1.0
 
 This document describes how to migrate an operator project built using Operator SDK `v0.0.x` to the project structure required by `v0.1.0`.
 
diff --git a/doc/migration/version-upgrade-guide.md b/doc/migration/version-upgrade-guide.md
@@ -1,4 +1,4 @@
-# Version upgrade guide
+# Operator SDK Version upgrade guide
 
 This document aims to facilitate the process of upgrading the Operator SDK version for an existing operator project.
 
diff --git a/doc/operator-scope.md b/doc/operator-scope.md
@@ -1,4 +1,4 @@
-## Operator scope
+# Operator SDK: Operator Scope
 
 A namespace-scoped operator watches and manages resources in a single namespace, whereas a cluster-scoped operator watches and manages resources cluster-wide. Namespace-scoped operators are preferred because of their flexibility. They enable decoupled upgrades, namespace isolation for failures and monitoring, and differing API definitions.
 
@@ -15,7 +15,7 @@ The SDK scaffolds operators to be namespaced by default but with a few modificat
   * Use `ClusterRole` instead of `Role` for `roleRef`
   * Set the subject namespace to the namespace in which the operator is deployed.
 
-### CRD scope
+## CRD scope
 
 Additionally the CustomResourceDefinition (CRD) scope can also be changed for cluster-scoped operators so that there is only a single instance (for a given name) of the CRD to manage across the cluster.
 
@@ -29,7 +29,7 @@ For each CRD that needs to be cluster-scoped, update its manifest to be cluster-
 To ensure that the CRD is always generated with `scope: Cluster`, add the tag `// +kubebuilder:resource:path=<resource>,scope=Cluster`, or if already present replace `scope={Namespaced -> Cluster}`, above the CRD's Go type defintion in `pkg/apis/<group>/<version>/<kind>_types.go`. The `<resource>` element must be the lower-case plural of the CRD's Kind, `spec.names.plural`.
 
 
-### Example for cluster scoped operator
+## Example for cluster scoped operator
 
 With the above changes the specified manifests should look as follows:
 
diff --git a/doc/project_layout.md b/doc/project_layout.md
@@ -1,4 +1,4 @@
-# Project Scaffolding Layout
+# Project Scaffolding Layout for Operator SDK
 
 The `operator-sdk` CLI generates a number of packages for each project. The following table describes a basic rundown of each generated file/directory.
 
diff --git a/doc/proposals/README.md b/doc/proposals/README.md
@@ -1,4 +1,4 @@
-# Proposals
+# Operator SDK Proposals
 
 This directory contains design documents for accepted proposals. To propose a new feature use the [template document][template]. Note that if the proposal gets accepted whoever is the proposal implementation owner is accepted to carry out the implementation, the implementation owner can be different to the proposal creator.
 
diff --git a/doc/proposals/TEMPLATE.md b/doc/proposals/TEMPLATE.md
@@ -1,4 +1,4 @@
-## <Title of Proposal>
+# <Title of Proposal> 
 
 Implementation Owner: < github username >
 Status: Draft
@@ -9,22 +9,22 @@ Status: Draft
 [User facing usage](#User_facing_usage)
 [Observations and open questions](#Observations_and_open_questions)
 
-### Background
+## Background
 
 < A paragraph or two on the background problem or missing feature on why this is needed. >
 
-### Goals
+## Goals
 
 < Short list of goals of this proposal >
 
-### Design overview
+## Design overview
 
 < Design of how the proposal architecture implementation would look like. >
 
-### User facing usage (if needed)
+## User facing usage (if needed)
 
 < If the user needs to interact with this feature, how would it look like from their point of view. >
 
-### Observations and open questions
+## Observations and open questions
 
 < Any open questions that need solving or implementation details should go here. These can be removed at the end of the proposal if they are resolved. >
diff --git a/doc/proposals/ansible-operator-status.md b/doc/proposals/ansible-operator-status.md
@@ -1,4 +1,4 @@
-# Ansible Operator Status Proposal
+# Ansible-based Operator Status Proposal for Operator SDK
 
 > Status: **completed**
 > 
diff --git a/doc/proposals/ansible-operator-testing.md b/doc/proposals/ansible-operator-testing.md
@@ -1,4 +1,4 @@
-# Ansible Operator Testing
+# Ansible based-Operator Testing Proposal for Operator SDK
 
 > Status: **completed**
 > 
diff --git a/doc/proposals/ansible-operator.md b/doc/proposals/ansible-operator.md
@@ -1,24 +1,24 @@
-## Ansible Operator Proposal
+# Ansible based-Operator Proposal for Operator SDK
 
 > Status: **completed**
 > 
 > This proposal has been completed, please see the [Ansible User Guide for Operator SDK](../ansible/user-guide.md) for current documentation.
 
-### Background
+## Background
 
 Not everyone is a golang developer, and therefore gaining adoption for the operator-sdk is capped by the number of golang developers. Also, tooling for Kubernetes in other languages is lacking support for things such as informers, caches, and listers.
 
 Operators purpose is to codify the operations of an application on Kubernetes. [Ansible](https://www.ansible.com/) is already an industry standard tool for automation and is a good fit for the kind of work that Kubernetes operators need to do. Adding the ability for users of the SDK to choose which between ansible and golang to follow will increase the number of potential users, and will grant existing users even more behavior.
 
-### Goals
+## Goals
 
 The goal of the Ansible Operator will be to create a fully functional framework for Ansible developers to create operators. It will also expose a library for golang users to use ansible in their operator if they so choose. These two goals in conjunction will allow users to select the best technology for their project or skillset.
 
-### New Operator Type
+## New Operator Type
 
 This proposal creates a new type of operator called `ansible`.  The new type is used to tell the tooling to act on that type of operator.
 
-### Package Structure
+## Package Structure
 Packages will be added to the operator-sdk. These packages are designed to be usable by the end user if they choose to and should have a well documented public API. The proposed packages are:
 * /operator-sdk/pkg/ansible/controller
   * Will contain the ansible operator controller.
@@ -42,7 +42,7 @@ Packages will be added to the operator-sdk. These packages are designed to be us
   * Default has only the event logger.
 
 
-### Commands
+## Commands
 We are adding and updating existing commands to accommodate the ansible operator.  Changes to the `cmd` package as well as changes to the generator are needed.
 
 `operator-sdk new <project-name> --type ansible --kind <kind> --api-version <group/version>`  This will be a new generation command under the hood. We will:
diff --git a/doc/proposals/cli-ux-phase1.md b/doc/proposals/cli-ux-phase1.md
@@ -1,4 +1,4 @@
-# User Experience CLI Improvements | Phase 1
+# User Experience CLI Improvements | Phase 1 Proposal for Operator SDK
 
 Implementation Owner: @joelanford
 
diff --git a/doc/proposals/helm-operator.md b/doc/proposals/helm-operator.md
@@ -1,20 +1,20 @@
-## Helm Operator Proposal
+# Helm based-Operator Proposal for Operator SDK
 
-### Background
+## Background
 
 As was mentioned in the [Ansible Operator Proposal](./ansible-operator.md), not everyone is a golang developer, so the SDK needs to support other types of operators to gain adoption across a wider community of users.
 
 [Helm](https://helm.sh/) is one of the most widely-used tools for Kubernetes application management, and it bills itself as the "package manager for Kubernetes." Operators serve a nearly identical function, but they improve on Helm's concepts by incorporating an always-on reconciliation loop rather than relying on an imperative user-driven command line tool. By integrating Helm's templating engine and release management into an operator, the SDK will further increase the number of potential users by adding the ability to deploy Charts (e.g. from Helm's [large catalog of existing Charts](https://github.com/helm/charts)) as operators with very little extra effort.
 
-### Goals
+## Goals
 
 The goal of the Helm Operator will be to create a fully functional framework for Helm Chart developers to create operators. It will also expose a library for golang users to use Helm in their operator if they so choose. These two goals in conjunction will allow users to select the best technology for their project or skillset.
 
-### New Operator Type
+## New Operator Type
 
 This proposal creates a new type of operator called `helm`. The new type is used to tell the tooling to act on that type of operator.
 
-### Package Structure
+## Package Structure
 
 Packages will be added to the operator-sdk. These packages are designed to be usable by the end user if they choose to and should have a well documented public API. The proposed packages are:
 
@@ -93,7 +93,7 @@ The resulting structure will be:
 
 The SDK CLI will use the presence of the `helm-charts` directory to detect a `helm` type project.
 
-#### Add
+### Add
 
 Add functionality will be updated to allow Helm operator developers to add new CRDs/CRs and to update the watches.yaml file for additional Helm charts. The command helps when a user wants to watch more than one CRD for their operator.
 
@@ -108,7 +108,7 @@ Flags:
 
 **NOTE:** `operator-sdk add` subcommands `api` and `controller` will not be supported, since they are only valid for Go operators. Running these subcommands in a Helm operator project will result in an error.
 
-#### Up
+### Up
 
 Up functionality will be updated to allow Helm operator developers to run their operator locally, using the `operator-sdk` binary's built-in helm operator implementation.
 
@@ -118,19 +118,19 @@ operator-sdk up local
 
 This should use the known structure and the helm operator code to run the operator from this location. The existing code will need to be updated with a new operator type check for `helm` (in addition to existing `go` and `ansible` types). The command works by running the operator-sdk binary, which includes the Helm operator code, as the operator process.
 
-#### Build
+### Build
 
 Build functionality will be updated to support building a docker image from the Helm operator directory structure.
 
 ```
 operator-sdk build <image-name>
 ```
 
-#### Test
+### Test
 
 The SDK `test` command currently only supports Go projects, so there will be no support for the `operator-sdk test` subcommand in the initial integration of the Helm operator.
 
-### Base Image
+## Base Image
 
 The SDK team will maintain a build job for the `helm-operator` base image with the following tagging methodology:
 * Builds on the master branch that pass nightly CI tests will be tagged with `:master`
@@ -140,7 +140,7 @@ The go binary included in the base image will be built with `GOOS=linux` and `GO
 
 The base image repository will be `quay.io/water-hole/helm-operator`.
 
-### Observations and open questions
+## Observations and open questions
 
 * There will be a large amount of overlap in the `operator-sdk` commands for the Ansible and Helm operators. We should take care to extract the reusable features of the Ansible operator commands into a shared library, usable by both Helm and Ansible commands.
 
diff --git a/doc/proposals/improved-scorecard-config.md b/doc/proposals/improved-scorecard-config.md
@@ -1,4 +1,4 @@
-# Improved Scorecard Config
+# Improved Scorecard Config Proposal for Operator SDK
 
 Implementation Owner: AlexNPavel
 Status: Draft
diff --git a/doc/proposals/leader-for-life.md b/doc/proposals/leader-for-life.md
@@ -1,4 +1,4 @@
-# Leader for Life
+# Leader for Life Proposal for Operator SDK
 
 ## Background
 
diff --git a/doc/proposals/metering-operator-metrics.md b/doc/proposals/metering-operator-metrics.md
@@ -1,10 +1,10 @@
-## Auto register operator specific metrics as part of operator-metering
+# Auto register operator specific metrics as part of operator-metering Proposal for Operator SDK
 
-### Motivation and goal
+## Motivation and goal
 
 We want to be able to generate the metering reports based on the operator specific Prometheus metrics. In order to be able to do that, operators must be instrumented to expose those metrics, and the operator-sdk should make this as easy as possible. The goal is to have the metering happen based on the usage of each individual operator. Metrics will be based on objects managed by the particular operator.
 
-### Overview of the metrics
+## Overview of the metrics
 
 To follow both the Prometheus instrumentation [best practices](https://prometheus.io/docs/practices/naming/) as well as the official Kubernetes instrumentation [guide](https://github.com/kubernetes/community/blob/cbe9c8ac5f71a99179d7ffe4a008b9018830af72/contributors/devel/sig-instrumentation/instrumentation.md), the metrics will have the following format:
 
@@ -18,7 +18,7 @@ example metric for the memchached-operator would look like this:
 memcached_info{namespace="default",memcached="example-memcached"} 1
 ```
 
-### kube-state-metrics based solution
+## kube-state-metrics based solution
 
 The solution makes use of Kubernetes list/watch to populate a Prometheus metrics registry, kube-state-metrics implements its own registry for performance reasons. [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics#overview) is used because it solves exactly the same problem we are facing but it does it for upstream known resources. The operator-sdk can re-use its functionality to perform the same thing but with custom resources. The kube-state-metrics library can only be used for constant (/static) metrics, metrics that are immutable and thereby entirely regenerated on change. This is perfect for our above mentioned use-case. It is not meant to do e.g. counting in performance critical code paths. Thereby an operator would need kube-state-metrics library for exposing the amount of custom resources that it manages and its details and Prometheus client_golang to expose metrics of its own internals e.g. count of reconciliation loops.
 
@@ -81,6 +81,6 @@ var (
 }
 ```
 
-### Related work
+## Related work
 
 In the future if the agreed on kube-state-metrics restructure happens (see https://github.com/kubernetes/kube-state-metrics/issues/579) we can get rid of some of the duplicated functions. But that will probably take a few months and our user facing interface should not change as a result.
diff --git a/doc/proposals/scorecard-plugin-system.md b/doc/proposals/scorecard-plugin-system.md
@@ -1,4 +1,4 @@
-# Plugin System for the Operator Scorecard
+# Plugin System for the `operator-sdk scorecard` feature Proposal for Operator SDK 
 
 Implementation Owner: AlexNPavel
 
diff --git a/doc/proposals/sdk-code-annotations.md b/doc/proposals/sdk-code-annotations.md
@@ -1,4 +1,4 @@
-# SDK Code Annotations
+# Code Annotations Proposal for Operator SDK
 
 Implementation Owner: @estroz
 
diff --git a/doc/proposals/tls-utilities.md b/doc/proposals/tls-utilities.md
@@ -1,4 +1,4 @@
-# TLS Utilities proposal
+# TLS Utilities Proposal for Operator SDK
 
 ## Background:
 
diff --git a/doc/sdk-cli-reference.md b/doc/sdk-cli-reference.md
diff --git a/doc/test-framework/scorecard.md b/doc/test-framework/scorecard.md
diff --git a/doc/user/client.md b/doc/user/client.md
diff --git a/doc/user/event-filtering.md b/doc/user/event-filtering.md
diff --git a/doc/user/logging.md b/doc/user/logging.md
diff --git a/doc/user/metrics/README.md b/doc/user/metrics/README.md
diff --git a/doc/user/metrics/service-monitor.md b/doc/user/metrics/service-monitor.md
diff --git a/doc/user/olm-catalog/generating-a-csv.md b/doc/user/olm-catalog/generating-a-csv.md
diff --git a/doc/user/unit-testing.md b/doc/user/unit-testing.md
diff --git a/doc/versioning.md b/doc/versioning.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Migrating an Ansible Playbook Bundle (APB) to an Ansible-based Operator`
	`1`	`+# Migrating an Ansible Playbook Bundle (APB) to an Operator SDK Ansible-based Operator`
`2`	`2`
`3`	`3`	`This guide will walk you through migrating your legacy Ansible Playbook Bundles (APB)`
`4`	`4`	`to a more modern Kubernetes Operator architecture. We will cover how to prepare a new`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Handling deletion events`
	`1`	`+# Handling Deletion Events with Operator SDK Ansible-based Operators`
`2`	`2`
`3`	`3`	`The default behavior of an Ansible Operator is to delete all resources the operator`
`4`	`4`	`created during reconciliation when a managed resource is marked for deletion. This`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Testing Ansible Operators with Molecule`
	`1`	`+# Testing Operator SDK Ansible-based Operators with Molecule`
`2`	`2`
`3`	`3`	`## Getting started`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Information Flow for Ansible Operator`
	`1`	`+# Information Flow for Operator SDK Ansible-based Operators`
`2`	`2`
`3`	`3`	`![Ansible Operator Flow](ao-flow.png)`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Project Scaffolding Layout`
	`1`	`+# Project Scaffolding Layout for Operator SDK Ansible-based Operators`
`2`	`2`
`3`	`3`	`After creating a new operator project using`
`4`	`4`	`operator-sdk new --type ansible`, the project directory has numerous generated folders and files. The following table describes a basic rundown of each generated file/directory.
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Releases`
	`1`	`+# Operator SDK Release guide`
`2`	`2`
`3`	`3`	`Making an Operator SDK release involves:`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Reporting bugs`
	`1`	`+# Reporting bugs in Operator SDK`
`2`	`2`
`3`	`3`	`If any part of the operator-sdk project has bugs or documentation mistakes, please let us know by [opening an issue][operator-sdk-issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Running the SDK Tests`
	`1`	`+# Running the Operator SDK Tests`
`2`	`2`
`3`	`3`	`The operator-sdk is automatically tested with a variety of tests anytime`
`4`	`4`	`a pull request is made. The E2E tests ensure that the operator-sdk acts as intended by`