Cleanup docs

ops-center · Jan 2, 2018 · bcb0d5e · bcb0d5e
1 parent 59686c5
commit bcb0d5e
Show file tree

Hide file tree

Showing 36 changed files with 281 additions and 182 deletions.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -6,7 +6,7 @@ menu:
     identifier: contributing-searchlight
     name: Contributing
     parent: welcome
-    weight: 35
+    weight: 10
 product_name: searchlight
 menu_name: product_searchlight_5.0.0
 section_menu_id: welcome
@@ -18,7 +18,7 @@ aliases:
 # Contribution Guidelines
 Want to hack on Searchlight?
 
-AppsCode projects are [Apache 2.0 licensed](LICENSE) and accept contributions via
+AppsCode projects are [Apache 2.0 licensed](https://github.com/appscode/searchlight/blob/master/LICENSE) and accept contributions via
 GitHub pull requests.  This document outlines some of the conventions on
 development workflow, commit message formatting, contact points and other
 resources to make it easier to get your contribution accepted.
@@ -28,25 +28,21 @@ resources to make it easier to get your contribution accepted.
 By contributing to this project you agree to the Developer Certificate of
 Origin (DCO). This document was created by the Linux Kernel community and is a
 simple statement that you, as a contributor, have the legal right to make the
-contribution. See the [DCO](DCO) file for details.
+contribution. See the [DCO](https://github.com/appscode/searchlight/blob/master/DCO) file for details.
 
 ## Developer Guide
 
-We have a [Developer Guide](/docs/developer-guide/README.md) that outlines everything you need to know from setting up your
+We have a [Developer Guide](/docs/setup/developer-guide/README.md) that outlines everything you need to know from setting up your
 dev environment to how to build and test Searchlight. If you find something undocumented or incorrect along the way,
 please feel free to send a Pull Request.
 
-## Design Docs
-
-If you want to know how Searchlight translates Alert CRDs into Icinga parlance, read the [design doc](docs/design/README.md).
-
 ## Getting Help
 
 If you have a question about Searchlight or having problem using it, you can contact us on our public Slack channel. Follow [this link](https://slack.appscode.com) to get invitation to our Slack channel.
 
 ## Bugs/Feature request
 
-If you have found a bug with Searchlight or want to request for new features, please [file an issue](https://github.com/appscode/searchlight/issues/new). 
+If you have found a bug with Searchlight or want to request for new features, please [file an issue](https://github.com/appscode/searchlight/issues/new).
 
 ## Submit PR
 

diff --git a/docs/README.md b/docs/README.md
@@ -15,53 +15,31 @@ aliases:
   - /products/searchlight/5.0.0/
   - /products/searchlight/5.0.0/README/
 ---
-
-[![Go Report Card](https://goreportcard.com/badge/github.com/appscode/searchlight)](https://goreportcard.com/report/github.com/appscode/searchlight)
-
 # Searchlight
 
 <img src="/docs/images/cover.jpg">
 
+Searchlight by AppsCode is a Kubernetes operator for [Icinga](https://www.icinga.com/). If you are running production workloads in Kubernetes, you probably want to be alerted when things go wrong. Icinga periodically runs various checks on a Kubernetes cluster and sends notifications if detects an issue. It also nicely supplements whitebox monitoring tools like, [Prometheus](https://prometheus.io/) with blackbox monitoring can catch problems that are otherwise invisible, and also serves as a fallback in case internal systems completely fail.
 
-Searchlight by AppsCode is a Kubernetes operator for [Icinga](https://www.icinga.com/). If you are running production workloads in Kubernetes, you probably want to be alerted when things go wrong. Icinga periodically runs various checks on a Kubernetes cluster and sends notifications if detects an issue. It also nicely supplements whitebox monitoring tools like, [Prometheus](https://prometheus.io/) with blackbox monitoring can catch problems that are otherwise invisible, and also serves as a fallback in case internal systems completely fail. Searchlight is a CRD controller for Kubernetes built around Icinga to address these issues. Searchlight can do the following things for you:
-
- - Periodically run various checks on a Kubernetes cluster and its nodes or pods.
- - Includes a [suite of check commands](/docs/reference/hyperalert/hyperalert.md) written specifically for Kubernetes.
- - Searchlight can send notifications via Email, SMS or Chat.
- - [Supplements](https://prometheus.io/docs/practices/alerting/#metamonitoring) the whitebox monitoring tools like [Prometheus](https://prometheus.io).
-
-## Supported Versions
-Please pick a version of Searchlight that matches your Kubernetes installation.
+From here you can learn all about Searchlight's architecture and how to deploy and use Searchlight.
 
-| Searchlight Version                                                                      | Docs                                                                       | Kubernetes Version |
-|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|--------------------|
-| [5.0.0](https://github.com/appscode/searchlight/releases/tag/5.0.0) (uses CRD)           | [User Guide](https://github.com/appscode/searchlight/tree/5.0.0/docs) | 1.7.x+             |
-| [3.0.1](https://github.com/appscode/searchlight/releases/tag/3.0.1) (uses TPR)           | [User Guide](https://github.com/appscode/searchlight/tree/3.0.1/docs)      | 1.5.x - 1.7.x      |
+- [Concepts](/docs/concepts/). Concepts explain some significant aspect of Searchlight. This is where you can learn about what Searchlight does and how it does it.
 
-## Installation
-To install Searchlight, please follow the guide [here](/docs/setup/install.md).
+- [Setup](/docs/setup/). Setup contains instructions for installing
+  the Searchlight in various cloud providers.
 
-## Using Searchlight
-Want to learn how to use Searchlight? Please start [here](/docs/guides/README.md).
+- [Guides](/docs/guides/). Guides show you how to perform tasks with Searchlight.
 
-## Contribution guidelines
-Want to help improve Searchlight? Please start [here](/docs/CONTRIBUTING.md).
-
-## Project Status
-Wondering what features are coming next? Please visit [here](/docs/roadmap.md).
-
----
+- [Reference](/docs/reference/). Detailed exhaustive lists of command-line options, configuration options, API definitions, and procedures.
 
-**The searchlight operator collects anonymous usage statistics to help us learn how the software is being used and
-how we can improve it. To disable stats collection, run the operator with the flag** `--analytics=false`.
+We're always looking for help improving our documentation, so please don't hesitate to
+[file an issue](https://github.com/appscode/searchlight/issues/new) if you see some problem.
+Or better yet, submit your own [contributions](/docs/CONTRIBUTING.md) to help
+make our docs better.
 
 ---
 
-## Acknowledgement
- - Many thanks to [Icinga](https://www.icinga.com/) project.
+**Searchlight binaries collects anonymous usage statistics to help us learn how the software is being used and how we can improve it.
+To disable stats collection, run the operator with the flag** `--analytics=false`.
 
-## Support
-If you have any questions, you can reach out to us.
-* [Slack](https://slack.appscode.com)
-* [Twitter](https://twitter.com/AppsCodeHQ)
-* [Website](https://appscode.com)
+---
diff --git a/docs/acknowledgement.md b/docs/acknowledgement.md
@@ -0,0 +1,19 @@
+---
+title: Acknowledgement | Searchlight
+description: Acknowledgement
+menu:
+  product_searchlight_5.0.0:
+    identifier: acknowledgement-searchlight
+    name: Acknowledgement
+    parent: welcome
+    weight: 20
+product_name: searchlight
+menu_name: product_searchlight_5.0.0
+section_menu_id: welcome
+url: /products/searchlight/5.0.0/welcome/acknowledgement/
+aliases:
+  - /products/searchlight/5.0.0/acknowledgement/
+---
+
+# Acknowledgement
+ - Many thanks to [Icinga](https://www.icinga.com/) project.
diff --git a/docs/concepts/README.md b/docs/concepts/README.md
@@ -13,7 +13,13 @@ url: /products/searchlight/5.0.0/concepts/
 aliases:
   - /products/searchlight/5.0.0/concepts/README/
 ---
-
 # Concepts
 
 Concepts help you learn about the different parts of the Searchlight and the abstractions it uses.
+
+- What is Searchlight?
+  - [Overview](/docs/concepts/what-is-searhclight/overview.md). Provides a conceptual introduction to Searchlight, including the problems it solves and its high-level architecture.
+- Types of Alerts
+  - [ClusterAlerts](/docs/concepts/alert-types/cluster-alert.md). Introduces the concept of `ClusterAlert` to periodically run various checks on a Kubernetes cluster.
+  - [NodeAlerts](/docs/concepts/alert-types/node-alert.md). Introduces the concept of `NodeAlert` to periodically run various checks on nodes in a Kubernetes cluster.
+  - [PodAlerts](/docs/concepts/alert-types/pod-alert.md). Introduces the concept of `PodAlert` to periodically run various checks on pods in a Kubernetes cluster.
diff --git a/docs/concepts/alert-types/_index.md b/docs/concepts/alert-types/_index.md
@@ -0,0 +1,11 @@
+---
+title: Types of Alerts
+description: Types of Alerts
+menu:
+  product_searchlight_5.0.0:
+    identifier: alert-types
+    parent: concepts
+    name: Types of Alerts
+    weight: 15
+menu_name: product_searchlight_5.0.0
+---
diff --git a/docs/guides/cluster-alerts/README.md → docs/concepts/alert-types/cluster-alert.md b/docs/guides/cluster-alerts/README.md → docs/concepts/alert-types/cluster-alert.md
@@ -3,15 +3,15 @@ title: Cluster Alert Overview
 menu:
   product_searchlight_5.0.0:
     identifier: cluster-alert-overview
-    name: Overview
-    parent: cluster-alert
+    name: Cluster Alert
+    parent: alert-types
     weight: 5
 product_name: searchlight
 menu_name: product_searchlight_5.0.0
-section_menu_id: guides
+section_menu_id: concepts
 ---
 
-> New to Searchlight? Please start [here](/docs/guides/README.md).
+> New to Searchlight? Please start [here](/docs/concepts/README.md).
 # ClusterAlerts
 
 ## What is ClusterAlert
@@ -85,8 +85,8 @@ You can skip this section if you are unfamiliar with how Icinga works. Searchlig
     - [json_path](/docs/guides/cluster-alerts/json_path.md) - To check any JSON HTTP response using [jq](https://stedolan.github.io/jq/).
     - [node_exists](/docs/guides/cluster-alerts/node_exists.md) - To check existence of Kubernetes nodes.
     - [pod_exists](/docs/guides/cluster-alerts/pod_exists.md) - To check existence of Kubernetes pods.
- - To periodically run various checks on nodes in a Kubernetes cluster, use [NodeAlerts](/docs/guides/node-alerts/README.md).
- - To periodically run various checks on pods in a Kubernetes cluster, use [PodAlerts](/docs/guides/pod-alerts/README.md).
+ - To periodically run various checks on nodes in a Kubernetes cluster, use [NodeAlerts](/docs/concepts/alert-types/node-alert.md).
+ - To periodically run various checks on pods in a Kubernetes cluster, use [PodAlerts](/docs/concepts/alert-types/pod-alert.md).
  - See the list of supported notifiers [here](/docs/guides/notifiers.md).
  - Wondering what features are coming next? Please visit [here](/docs/roadmap.md).
  - Want to hack on Searchlight? Check our [contribution guidelines](/docs/CONTRIBUTING.md).
diff --git a/docs/guides/node-alerts/README.md → docs/concepts/alert-types/node-alert.md b/docs/guides/node-alerts/README.md → docs/concepts/alert-types/node-alert.md
@@ -3,15 +3,15 @@ title: Node Alert Overview
 menu:
   product_searchlight_5.0.0:
     identifier: node-alert-overview
-    name: Overview
-    parent: node-alert
+    name: Node Alert
+    parent: alert-types
     weight: 10
 product_name: searchlight
 menu_name: product_searchlight_5.0.0
-section_menu_id: guides
+section_menu_id: concepts
 ---
 
-> New to Searchlight? Please start [here](/docs/guides/README.md).
+> New to Searchlight? Please start [here](/docs/concepts/README.md).
 
 # NodeAlerts
 
@@ -91,8 +91,8 @@ You can skip this section if you are unfamiliar with how Icinga works. Searchlig
     - [influx_query](/docs/guides/node-alerts/influx_query.md) - To check InfluxDB query result.
     - [node_status](/docs/guides/node-alerts/node_status.md) - To check Kubernetes Node status.
     - [node_volume](/docs/guides/node-alerts/node_volume.md) - To check Node Disk stat.
- - To periodically run various checks on a Kubernetes cluster, use [ClusterAlerts](/docs/guides/cluster-alerts/README.md).
- - To periodically run various checks on pods in a Kubernetes cluster, use [PodAlerts](/docs/guides/pod-alerts/README.md).
+ - To periodically run various checks on a Kubernetes cluster, use [ClusterAlerts](/docs/concepts/alert-types/cluster-alert.md).
+ - To periodically run various checks on pods in a Kubernetes cluster, use [PodAlerts](/docs/concepts/alert-types/pod-alert.md).
  - See the list of supported notifiers [here](/docs/guides/notifiers.md).
  - Wondering what features are coming next? Please visit [here](/docs/roadmap.md).
  - Want to hack on Searchlight? Check our [contribution guidelines](/docs/CONTRIBUTING.md).
diff --git a/docs/guides/pod-alerts/overview.md → docs/concepts/alert-types/pod-alert.md b/docs/guides/pod-alerts/overview.md → docs/concepts/alert-types/pod-alert.md
@@ -3,15 +3,15 @@ title: Pod Alert Overview
 menu:
   product_searchlight_5.0.0:
     identifier: pod-alert-overview
-    name: Overview
-    parent: pod-alert
-    weight: 10
+    name: Pod Alert
+    parent: alert-types
+    weight: 15
 product_name: searchlight
 menu_name: product_searchlight_5.0.0
-section_menu_id: guides
+section_menu_id: concepts
 ---
 
-> New to Searchlight? Please start [here](/docs/guides/README.md).
+> New to Searchlight? Please start [here](/docs/concepts/README.md).
 
 # PodAlerts
 
@@ -95,8 +95,8 @@ You can skip this section if you are unfamiliar with how Icinga works. Searchlig
     - [pod_exec](/docs/guides/pod-alerts/pod_exec.md) - To check Kubernetes exec command. Returns OK if exit code is zero, otherwise, returns CRITICAL
     - [pod_status](/docs/guides/pod-alerts/pod_status.md) - To check Kubernetes pod status.
     - [pod_volume](/docs/guides/pod-alerts/pod_volume.md) - To check Pod volume stat.
- - To periodically run various checks on a Kubernetes cluster, use [ClusterAlerts](/docs/guides/cluster-alerts/README.md).
- - To periodically run various checks on nodes in a Kubernetes cluster, use [NodeAlerts](/docs/guides/node-alerts/README.md).
+ - To periodically run various checks on a Kubernetes cluster, use [ClusterAlerts](/docs/concepts/alert-types/cluster-alert.md).
+ - To periodically run various checks on nodes in a Kubernetes cluster, use [NodeAlerts](/docs/concepts/alert-types/node-alert.md).
  - See the list of supported notifiers [here](/docs/guides/notifiers.md).
  - Wondering what features are coming next? Please visit [here](/docs/roadmap.md).
  - Want to hack on Searchlight? Check our [contribution guidelines](/docs/CONTRIBUTING.md).
diff --git a/docs/concepts/what-is-searhclight/_index.md b/docs/concepts/what-is-searhclight/_index.md
@@ -0,0 +1,11 @@
+---
+title: What is Searchlight
+description: What is Searchlight
+menu:
+  product_searchlight_5.0.0:
+    identifier: what-is-searchlight
+    parent: concepts
+    name: What is Searchlight
+    weight: 10
+menu_name: product_searchlight_5.0.0
+---
diff --git a/docs/concepts/overview.md → .../concepts/what-is-searhclight/overview.md b/docs/concepts/overview.md → .../concepts/what-is-searhclight/overview.md
@@ -1,11 +1,11 @@
 ---
-title: Concepts | Searchlight
-description: Overview of Concepts
+title: Searchlight Overview
+description: Searchlight Overview
 menu:
   product_searchlight_5.0.0:
     identifier: overview-concepts
     name: Overview
-    parent: concepts
+    parent: what-is-searchlight
     weight: 10
 product_name: searchlight
 menu_name: product_searchlight_5.0.0

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -1,6 +1,6 @@
 ---
-title: Readme
-description: Readme of guides
+title: Table of Contents | Guides
+description: Table of Contents | Guides
 menu:
   product_searchlight_5.0.0:
     identifier: guides-readme
@@ -14,28 +14,27 @@ url: /products/searchlight/5.0.0/guides/
 aliases:
   - /products/searchlight/5.0.0/guides/README/
 ---
-
 # Guides
 
-This section contains guides on how to use Searchlight. Please visit the links below to learn more:
+Guides show you how to perform tasks with Searchlight.
 
- - [ClusterAlerts](/docs/guides/cluster-alerts/README.md) - This article introduces the concept of `ClusterAlert` to periodically run various checks on a Kubernetes cluster. Also, visit the links below to learn about the available check commands for a cluster:
-    - [ca_cert](/docs/guides/cluster-alerts/ca_cert.md) - To check expiration of CA certificate used by Kubernetes api server.
-    - [component_status](/docs/guides/cluster-alerts/component_status.md) - To check Kubernetes component status.
-    - [event](/docs/guides/cluster-alerts/event.md) - To check Kubernetes Warning events.
-    - [json_path](/docs/guides/cluster-alerts/json_path.md) - To check any JSON HTTP response using [jq](https://stedolan.github.io/jq/).
-    - [node_exists](/docs/guides/cluster-alerts/node_exists.md) - To check existence of Kubernetes nodes.
-    - [pod_exists](/docs/guides/cluster-alerts/pod_exists.md) - To check existence of Kubernetes pods.
+- Cluster Alerts
+  - [ca_cert](/docs/guides/cluster-alerts/ca_cert.md) - To check expiration of CA certificate used by Kubernetes api server.
+  - [component_status](/docs/guides/cluster-alerts/component_status.md) - To check Kubernetes component status.
+  - [event](/docs/guides/cluster-alerts/event.md) - To check Kubernetes Warning events.
+  - [json_path](/docs/guides/cluster-alerts/json_path.md) - To check any JSON HTTP response using [jq](https://stedolan.github.io/jq/).
+  - [node_exists](/docs/guides/cluster-alerts/node_exists.md) - To check existence of Kubernetes nodes.
+  - [pod_exists](/docs/guides/cluster-alerts/pod_exists.md) - To check existence of Kubernetes pods.
 
- - [NodeAlerts](/docs/guides/node-alerts/README.md) - This article introduces the concept of `NodeAlert` to periodically run various checks on nodes in a Kubernetes cluster. Also, visit the links below to learn about the available check commands for nodes:
-    - [influx_query](/docs/guides/node-alerts/influx_query.md) - To check InfluxDB query result.
-    - [node_status](/docs/guides/node-alerts/node_status.md) - To check Kubernetes Node status.
-    - [node_volume](/docs/guides/node-alerts/node_volume.md) - To check Node Disk stat.
+- Node Alerts
+  - [influx_query](/docs/guides/node-alerts/influx_query.md) - To check InfluxDB query result.
+  - [node_status](/docs/guides/node-alerts/node_status.md) - To check Kubernetes Node status.
+  - [node_volume](/docs/guides/node-alerts/node_volume.md) - To check Node Disk stat.
 
- - [PodAlerts](/docs/guides/pod-alerts/README.md) - This article introduces the concept of `PodAlert` to periodically run various checks on pods in a Kubernetes cluster. Also, visit the links below to learn about the available check commands for pods:
-    - [influx_query](/docs/guides/pod-alerts/influx_query.md) - To check InfluxDB query result.
-    - [pod_exec](/docs/guides/pod-alerts/pod_exec.md) - To check Kubernetes exec command. Returns OK if exit code is zero, otherwise, returns CRITICAL
-    - [pod_status](/docs/guides/pod-alerts/pod_status.md) - To check Kubernetes pod status.
-    - [pod_volume](/docs/guides/pod-alerts/pod_volume.md) - To check Pod volume stat.
+- Pod Alerts
+  - [influx_query](/docs/guides/pod-alerts/influx_query.md) - To check InfluxDB query result.
+  - [pod_exec](/docs/guides/pod-alerts/pod_exec.md) - To check Kubernetes exec command. Returns OK if exit code is zero, otherwise, returns CRITICAL
+  - [pod_status](/docs/guides/pod-alerts/pod_status.md) - To check Kubernetes pod status.
+  - [pod_volume](/docs/guides/pod-alerts/pod_volume.md) - To check Pod volume stat.
 
- - [Supported Notifiers](/docs/guides/notifiers.md): This article documents how to configure Searchlight to send notifications via Email, SMS or Chat.
+- [Supported Notifiers](/docs/guides/notifiers.md): This article documents how to configure Searchlight to send notifications via Email, SMS or Chat.