Refactoring the left-hand navigation panel. (#406)

* In progress: Refactoring the left-hand navigation panel.

* Added .description to section index pages.

* Removed the redundant Components Overview as the new index page of the components section does a better job.

* Added redirects for the files I've moved/deleted.

* Fixed the URLs in all doc links.

README.md

@@ -132,7 +132,7 @@ A `weight` property in the _front matter_ of each page determines the position
 of the page relative to the others in the same directory. The lower the weight,
 the earlier the page appears in the section. A weight of 1 appears before a
 a weight of 2, and so on. For example, see the front matter of the
-[requirements](https://github.com/kubeflow/website/blob/master/content/docs/guides/requirements.md)
+[requirements](https://github.com/kubeflow/website/blob/master/content/docs/started/requirements.md)
 page in the guides section. The page front matter looks like this:
 
 ```

content/_redirects

@@ -12,4 +12,8 @@
 /blog/kaggle_on_kubeflow/              https://medium.com/kubeflow/kaggle-on-kubeflow-185a29e27c53
 /blog/announcing_kubeflow_0.2/         https://medium.com/kubeflow/kubeflow-0-2-offers-new-components-and-simplified-setup-735e4c56988d
 
-/docs/guides/pipelines/deploy-pipelines-service/  /docs/guides/pipelines/pipelines-quickstart/
+/docs/guides/components/components     /docs/components/
+/docs/guides/pipelines/deploy-pipelines-service/  /docs/pipelines/pipelines-quickstart/
+
+# Removed the "guides" section from the doc URLs.
+/docs/guides/*  /docs/:splat

content/docs/components/_index.md

@@ -1,5 +1,5 @@
 +++
 title = "Components of Kubeflow"
 description = "Logical components that make up Kubeflow"
-weight = 2
+weight = 7
 +++

content/docs/components/jupyter.md

@@ -6,7 +6,7 @@ weight = 10
 
 ## Bringing up a Jupyter Notebook
 
-1. To connect to Jupyter follow the [instructions](/docs/guides/accessing-uis)
+1. To connect to Jupyter follow the [instructions](/docs/other-guides/accessing-uis)
 to access the Kubeflow UI. From there you will be able to navigate to JupyterHub   
    ![JupyterHub Link](/docs/images/jupyterlink.png)
 1. Sign in 

content/docs/components/ksonnet.md

@@ -77,7 +77,7 @@ ks apply default
 
 ## Upgrading ksonnet
 
-See the guide to [upgrading Kubeflow](/docs/guides/upgrade/).
+See the guide to [upgrading Kubeflow](/docs/other-guides/upgrade/).
 
 ## Why Kubeflow uses ksonnet
 

content/docs/components/pipelines.md

@@ -17,5 +17,5 @@ The Kubeflow Pipelines platform has the following goals:
   cobble together end-to-end solutions, without having to rebuild each time.
 
   Read more in the 
-  [pipelines section](/docs/guides/pipelines/pipelines-overview)
+  [pipelines section](/docs/pipelines/pipelines-overview)
   of the documentation.

content/docs/components/pytorchserving.md

@@ -7,7 +7,7 @@ This guide walks you through serving a PyTorch trained model in Kubeflow.
 
 ## Serving a model
 
-We use [seldon-core](https://github.com/SeldonIO/seldon-core) component deployed following [these](/docs/guides/components/seldon/) instructions to serve the model.
+We use [seldon-core](https://github.com/SeldonIO/seldon-core) component deployed following [these](/docs/components/seldon/) instructions to serve the model.
 
 See also this [Example module](https://github.com/kubeflow/examples/blob/master/pytorch_mnist/serving/seldon-wrapper/mnistddpserving.py) which contains the code to wrap the model with Seldon. 
 

content/docs/components/tfserving_new.md

@@ -153,8 +153,8 @@ python iap_request.py https://YOUR_HOST/tfserving/models/mnist IAP_CLIENT_ID --i
 
 ## Telemetry and Rolling out model using Istio
 
-Please look at the [Istio guide](/docs/guides/components/istio/).
+Please look at the [Istio guide](/docs/components/istio/).
 
 ## Logs and metrics with Stackdriver
-See [here](/docs/guides/monitoring/) for instructions to get logs and metrics
+See [here](/docs/other-guides/monitoring/) for instructions to get logs and metrics
 using Stackdriver.

content/docs/components/tftraining.md

@@ -238,7 +238,7 @@ The TFJob dashboard is available at `<path>/tfjobs/ui/`. Specifically:
     http://localhost:8080/tfjobs/ui/
     ```
 
-See more details about [accessing the Kubeflow UIs](/docs/guides/accessing-uis).
+See more details about [accessing the Kubeflow UIs](/docs/other-guides/accessing-uis).
 
 ## Using GPUs
 
@@ -577,9 +577,9 @@ further analysis.
 
 ### Stackdriver on GKE
 
-See [here](/docs/guides/monitoring/) for instructions to get logs using Stackdriver.
+See [here](/docs/other-guides/monitoring/) for instructions to get logs using Stackdriver.
 
-As described [here](https://www.kubeflow.org/docs/guides/monitoring/#filter-with-labels) its possible
+As described [here](https://www.kubeflow.org/docs/other-guides/monitoring/#filter-with-labels) its possible
 to fetch the logs for a particular replica based on pod labels. 
 
 Using the Stackdriver UI you can use a query like
@@ -685,4 +685,4 @@ Events:
    in the previous section.
 
 ## More information
-* See how to [run a job with gang-scheduling](/docs/guides/job-scheduling).
+* See how to [run a job with gang-scheduling](/docs/other-guides/job-scheduling).

content/docs/gke/_index.md

@@ -1,5 +1,5 @@
 +++
 title = "Kubeflow on GKE"
 description = "Running Kubeflow on Kubernetes Engine and GCP"
-weight = 4
+weight = 5
 +++

content/docs/gke/cloud-filestore.md

@@ -57,7 +57,7 @@ ${KUBEFLOW_SRC}/scripts/kfctl.sh apply platform
 ```
 
 If you get an error **legacy networks are not supported** follow the instructions
-in the [troubleshooting guide](/docs/guides/troubleshooting).
+in the [troubleshooting guide](/docs/other-guides/troubleshooting).
 
 ## Configure Kubeflow to mount the Cloud Filestore volume
 

content/docs/gke/customizing-gke.md

@@ -104,5 +104,5 @@ For more information please refer to the [Deployment Manager docs](https://cloud
 ## More customizations
 
 Refer to the navigation panel on the left of these docs for more customizations,
-including [using your own domain](/docs/guides/gke/custom-domain), 
-[setting up Cloud Filestore](/docs/guides/gke/cloud-filestore), and more.
+including [using your own domain](/docs/gke/custom-domain), 
+[setting up Cloud Filestore](/docs/gke/cloud-filestore), and more.

content/docs/gke/gcp-e2e.md

@@ -207,7 +207,7 @@ ksonnet components as standard Kubernetes YAML files with `ks show`, or you can
 deploy (_apply_) the components directly to the cluster with `ks apply`.
 
 Make sure you have the version of ksonnet specified in the 
-[Kubeflow requirements](/docs/guides/requirements).
+[Kubeflow requirements](/docs/started/requirements).
 
 Follow the steps below to install ksonnet:
 
@@ -1029,10 +1029,10 @@ gsutil rm -r gs://${BUCKET_NAME}
 [kubeflow-core]: https://github.com/kubeflow/kubeflow/tree/master/kubeflow/core
 [tf-job-prototype]: https://github.com/kubeflow/kubeflow/blob/master/kubeflow/examples/prototypes/tf-job-simple.jsonnet
 [tf-serving-prototype]: https://github.com/kubeflow/kubeflow/tree/master/kubeflow/tf-serving
-[tf-training]: /docs/guides/components/tftraining/
+[tf-training]: /docs/components/tftraining/
 
 [deploy-script]: https://github.com/kubeflow/kubeflow/blob/master/scripts/gke/deploy.sh
 
 [jupyterhub]: http://jupyter.org/hub
-[kubeflow-jupyter]: /docs/guides/components/jupyter/
+[kubeflow-jupyter]: /docs/components/jupyter/
 [jupyter-nbviewer]: https://jupyter-notebook.readthedocs.io/en/latest/notebook.html#notebook-user-interface

content/docs/gke/troubleshooting-gke.md

@@ -13,7 +13,7 @@ This guide covers troubleshooting specifically for
 [Kubeflow deployments on GKE](/docs/started/getting-started-gke).
 
 For more help, try the 
-[general Kubeflow troubleshooting guide](/docs/guides/troubleshooting).
+[general Kubeflow troubleshooting guide](/docs/other-guides/troubleshooting).
 
 ## Troubleshooting Cloud IAP
 
@@ -268,7 +268,7 @@ ${KUBEFLOW_SRC}/scripts/kfctl.sh apply platform
 ## CPU platform unavailable in requested zone
 
 By default we set minCpuPlatform to `Intel Haswell` to make sure AVX2 is supported.
-See [troubleshooting](/docs/guides/troubleshooting/) for more details.
+See [troubleshooting](/docs/other-guides/troubleshooting/) for more details.
 
 If you encounter this `CPU platform unavailable` error (might manifest as
 `Cluster is currently being created, deleted, updated or repaired and cannot be updated.`),

content/docs/guides/_index.md

@@ -1,5 +0,0 @@
-+++
-title = "Guides"
-description = "Step-by-step instructions on how to use Kubeflow"
-weight = 3
-+++

content/docs/guides/components/components.md

@@ -1,15 +0,0 @@
-+++
-title = "Components Overview"
-description = "Kubeflow components"
-weight = 1
-aliases = ["/docs/guides/components/", "/docs/components/"]
-+++
-
-Kubeflow offers scripts and configuration files to activate a number of
-supported components. To use Kubeflow, you choose the services that you want
-to use for each stage of the ML workflow (data preparation, model training,
-serving predictions, service management).
-
-The *components* section of the documentation describes the supported
-components and their configuration. See the left-hand navigation panel for
-a list of components.

content/docs/other-guides/_index.md

@@ -0,0 +1,5 @@
++++
+title = "Other Guides"
+description = "Various instructions on how to use Kubeflow"
+weight = 8
++++

content/docs/other-guides/troubleshooting.md

@@ -151,7 +151,7 @@ export GITHUB_TOKEN=<< token >>
 
 ## ks apply produces error "Unknown variable: env"
 
-Kubeflow requires a [specific version of ksonnet](/docs/guides/requirements).
+Kubeflow requires a [specific version of ksonnet](/docs/started/requirements).
 If you run `ks apply` with an older version of ksonnet you will likely get the error `Unknown variable: env` as illustrated below:
 
 ```shell
@@ -167,7 +167,7 @@ You can check the ksonnet version as follows:
 ks version
 ```
 
-If your ksonnet version is lower than what is specified in the [requirements](/docs/guides/requirements), please upgrade it and follow the [guide](/docs/guides/components/ksonnet) to recreate the app.
+If your ksonnet version is lower than what is specified in the [requirements](/docs/started/requirements), please upgrade it and follow the [guide](/docs/components/ksonnet) to recreate the app.
 
 ## ksonnet on Windows
 There are some known issues with ksonnet and Windows. You might consider 

content/docs/pipelines/_index.md

@@ -1,5 +1,5 @@
 +++
 title = "Pipelines"
 description = "Documentation for Kubeflow Pipelines."
-weight = 3
+weight = 4
 +++

content/docs/pipelines/build-component.md

@@ -6,15 +6,15 @@ weight = 6
 
 This page is for advanced users. It describes how to build your own pipeline 
 components. For an easier start, try 
-[building a pipeline with the provided samples](/docs/guides/pipelines/build-pipeline).
+[building a pipeline with the provided samples](/docs/pipelines/build-pipeline).
 
 ## Overview of pipeline components
 
 Kubeflow Pipelines components are implementations of pipeline tasks. Each task 
 takes one or more 
-[artifacts](/docs/guides/pipelines/pipelines-concepts#step-output-artifacts) as
+[artifacts](/docs/pipelines/pipelines-concepts#step-output-artifacts) as
 input and may produce one or more
-[artifacts](/docs/guides/pipelines/pipelines-concepts#step-output-artifacts) as 
+[artifacts](/docs/pipelines/pipelines-concepts#step-output-artifacts) as 
 output.
 
 Each task usually includes two parts:
@@ -44,7 +44,7 @@ There are multiple ways to author components:
 * Wrap an existing Docker container image using `ContainerOp`, as described 
   below.
 * Create a 
-  [lightweight python component](/docs/guides/pipelines/lightweight-python-components) 
+  [lightweight python component](/docs/pipelines/lightweight-python-components) 
   from a Python function
 * Build a new Docker container image from a Python function.
 
@@ -167,8 +167,8 @@ See [an example](https://github.com/kubeflow/pipelines/blob/master/samples/xgboo
 
 You can also build lightweight components from Python functions. See the guide 
 to 
-[lightweight python components](/docs/guides/pipelines/lightweight-python-components).
+[lightweight python components](/docs/pipelines/lightweight-python-components).
 
 ## Export metrics
 
-See the guide to [pipeline metrics](/docs/guides/pipelines/pipelines-metrics).
+See the guide to [pipeline metrics](/docs/pipelines/pipelines-metrics).

content/docs/pipelines/build-pipeline.md

@@ -138,4 +138,4 @@ Upload the generated `.tar.gz` file through the Kubeflow Pipelines UI.
 ## Advanced: Build your own components
 
 See how to 
-[build your own pipeline components](/docs/guides/pipelines/build-component).
+[build your own pipeline components](/docs/pipelines/build-component).

content/docs/pipelines/pipelines-concepts.md

@@ -23,7 +23,7 @@ A building block in the pipeline template; self-contained user code that
 performs one step in the pipeline, such as preprocessing, transformation, 
 training, etc. A component must be packaged as a 
 [Docker image](https://docs.docker.com/get-started/). See the guide to
-[building your own components](/docs/guides/pipelines/build-component).
+[building your own components](/docs/pipelines/build-component).
 
 ## Experiment
 

content/docs/pipelines/pipelines-metrics.md

@@ -3,7 +3,7 @@ title = "Pipeline metrics"
 description = "Export and visualize pipeline metrics."
 weight = 9
 +++
-This page shows you how to export metrics from the component. For details about how to build a component, see the guide to [building your own component](/docs/guides/pipelines/build-component).
+This page shows you how to export metrics from the component. For details about how to build a component, see the guide to [building your own component](/docs/pipelines/build-component).
  
 ## Overview of metrics
 

content/docs/pipelines/pipelines-overview.md

@@ -162,4 +162,5 @@ Receiver operating characteristics (ROC) curve:
   deploy Kubeflow and run a sample pipeline directly from the 
   Kubeflow Pipelines UI.
 * Follow the full guide to
-  [building a pipeline](/docs/guides/pipelines/build-pipeline).
+  [building a pipeline](/docs/guides/pipelines/build-pipeline).
+  

content/docs/pipelines/pipelines-quickstart.md

@@ -6,7 +6,7 @@ weight = 1
 
 Use this guide if you want to get a simple pipeline running quickly in
 Kubeflow Pipelines. If you need a more in-depth guide, see how to
-[build a pipeline](/docs/guides/pipelines/build-pipeline/).
+[build a pipeline](/docs/pipelines/build-pipeline/).
 
 ## Deploy Kubeflow and open the pipelines UI
 
@@ -160,9 +160,9 @@ finished with them:
 ## Next steps
 
 * Learn more about the 
-  [important concepts](/docs/guides/pipelines/pipelines-concepts) in Kubeflow
+  [important concepts](/docs/pipelines/pipelines-concepts) in Kubeflow
   Pipelines.
 * This page showed you how to run some of the examples supplied in the Kubeflow
   Pipelines UI. Next, you may want to run a pipeline from a notebook, or compile 
   and run a sample from the code. See the guide to 
-  [building a pipeline](/docs/guides/pipelines/build-pipeline/).
+  [building a pipeline](/docs/pipelines/build-pipeline/).

content/docs/pipelines/pipelines-samples.md

@@ -142,4 +142,4 @@ Upload the generated `.tar.gz` file through the Kubeflow Pipelines UI.
 ## Advanced: Build your own components
 
 See how to 
-[build your own pipeline components](/docs/guides/pipelines/build-component).
+[build your own pipeline components](/docs/pipelines/build-component).

content/docs/pipelines/pipelines-ui.md

@@ -118,7 +118,7 @@ the page displaying the name of the run and containing its own three tabs:
 ### Artifacts
 
 Artifacts are any 
-[viewers](/docs/guides/pipelines/output-viewer) associated with a given 
+[viewers](/docs/pipelines/output-viewer) associated with a given 
 component. There are many kinds of viewers including: 
 
 * TensorBoard instances (accessible via link)

content/docs/started/getting-started-gke.md

@@ -280,10 +280,10 @@ privilege. The three service accounts are:
 ## Next steps
 
 * Run a full ML workflow on Kubeflow, using the
-  [end-to-end MNIST tutorial](/docs/guides/gke/gcp-e2e/) or the
+  [end-to-end MNIST tutorial](/docs/gke/gcp-e2e/) or the
   [GitHub issue sumarization 
   example](https://github.com/kubeflow/examples/tree/master/github_issue_summarization).
-* See how to [customize](/docs/guides/gke/customizing-gke) your Kubeflow 
+* See how to [customize](/docs/gke/customizing-gke) your Kubeflow 
   deployment on GKE.
-* [Troubleshoot](/docs/guides/gke/troubleshooting-gke) any issues you may
+* [Troubleshoot](/docs/gke/troubleshooting-gke) any issues you may
   find.

content/docs/started/getting-started-minikube.md

@@ -249,6 +249,6 @@ For JupyterHub, you'll be landing on a login page.
   - You should be redirected to a page that waits while the server is starting.
 
 If the page doesn't refresh, please see
-[troubleshooting](/docs/guides/troubleshooting/#problems-spawning-jupyter-pods).
+[troubleshooting](/docs/other-guides/troubleshooting/#problems-spawning-jupyter-pods).
 
-For further exploration refer to the [guide](/docs/guides/).
+For further exploration refer to the [documentation](/docs/).

content/docs/started/getting-started-multipass.md

@@ -122,6 +122,6 @@ Point browser to either:
 
 ### Where to go next
 
-* Refer to the [user guide](/docs/guides/)
-* Refer to the [components](/docs/guides/components/)
-* Refer to the [JupyterHub guide](/docs/guides/components/jupyter)
+* Refer to the [user guide](/docs/)
+* Refer to the [components](/docs/components/)
+* Refer to the [JupyterHub guide](/docs/components/jupyter)

content/docs/started/getting-started.md

@@ -76,14 +76,14 @@ Download, set up, and deploy (If you prefer to work from source code, feel free
    * (optional) For GPU support, make sure your cluster is in a [zone that has GPUs](https://cloud.google.com/compute/docs/regions-zones/). To set the zone explicitly, append `--zone ${ZONE}` to the `init` command.
 
 **Important**: The commands above will enable collection of **anonymous** user data to help us improve Kubeflow; for more information including instructions for explicitly
-disabling it please refer to the [usage reporting guide](/docs/guides/usage-reporting/).
+disabling it please refer to the [usage reporting guide](/docs/other-guides/usage-reporting/).
 
 ## Troubleshooting
-For detailed troubleshooting instructions, please refer to the [troubleshooting guide](/docs/guides/troubleshooting/).
+For detailed troubleshooting instructions, please refer to the [troubleshooting guide](/docs/other-guides/troubleshooting/).
 
 ## Resources
 
-* The [guides section](/docs/guides/) provides in-depth instructions for using Kubeflow
+* The [documentation](/docs/) provides in-depth instructions for using Kubeflow
 * Self-paced scenarios for learning and trying out Kubeflow:
   * [Codelabs](https://codelabs.developers.google.com/?cat=tensorflow)
       * [Introduction to Kubeflow on Google Kubernetes Engine](https://codelabs.developers.google.com/codelabs/kubeflow-introduction/index.html)

content/docs/started/requirements.md

@@ -1,7 +1,7 @@
 +++
 title = "Requirements"
 description = "Requirements for Kubeflow"
-weight = 1
+weight = 5
 +++
 
 The guides in this section give detailed information about using Kubeflow and 
@@ -16,7 +16,7 @@ the following systems:
 
 ## Kubeflow requirements
 
- * ksonnet version {{% ksonnet-min-version %}} or later. See the [ksonnet component page](/docs/guides/components/ksonnet/) for an explanation of why we use ksonnet.
+ * ksonnet version {{% ksonnet-min-version %}} or later. See the [ksonnet component page](/docs/components/ksonnet/) for an explanation of why we use ksonnet.
  * An existing Kubernetes cluster using Kubernetes {{% kubernetes-min-version %}} or later:
    * A minimum of 0.6 CPU in cluster (Reserved for 3 replicated ambassador pods and according to your need add additional CPUs)
    * Node with storage >= 10 GB (Due to the ML libraries and third party packages being bundled in Kubeflow Docker images)

content/docs/use-cases/_index.md

@@ -0,0 +1,5 @@
++++
+title = "Use Cases"
+description = "Guides to specific ways of using Kubeflow."
+weight = 3
++++

layouts/docs/list.html

@@ -1,8 +1,9 @@
 {{ define "title"}} {{ .Title}} {{end}}
 {{ define "main" }}
 
-<div id="hero" class="wrap">
+<div id="hero" class="wrap td-content ">
   <h1>{{ .Title }}</h1>
+  {{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
 </div>
 
 <section id="pageContent">