revisions, edits, and fixes (#944)

rosemarymarano · markxnelson · commit 3fada0c36539 · 2019-03-18T17:29:57.000-04:00
* revisions, edits, and fixes

* few more fixes

* fix typo
diff --git a/docs-source/content/_index.md b/docs-source/content/_index.md
@@ -21,12 +21,6 @@ The [current release of the operator](https://github.com/oracle/weblogic-kuberne
 This release was published on March 4, 2019.
 ***
 
-#### Known issues
-
-| Issue | Description |
-| --- | --- |
-| None currently |  |
-
 #### Operator earlier versions
 
 Documentation for prior releases of the operator is available [here](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/site/README.md).
@@ -79,9 +73,9 @@ or suggestions about what features and improvements you would like to see.  We w
 please [visit this site to get an invitation](https://weblogic-slack-inviter.herokuapp.com/).  The invitation email will include
 details of how to access our Slack workspace.  After you are logged in, please come to `#operator` and say, "hello!"
 
-### Recent changes
+### Recent changes and known issues
 
-See [Recent changes]({{< relref "release-notes.md" >}})  for changes to the operator, including any backward incompatible changes.
+See the [Release Notes]({{< relref "release-notes.md" >}})  for recent changes to the operator and known issues.
 
 ### Developer guide
 
@@ -136,31 +130,3 @@ Only pull requests from committers that can be verified as having signed the OCA
 #### Introducing a new dependency
 
 Please be aware that pull requests that seek to introduce a new dependency will be subject to additional review.  In general, contributors should avoid dependencies with incompatible licenses, and should try to use recent versions of dependencies.  Standard security vulnerability checklists will be consulted before accepting a new dependency.  Dependencies on closed-source code, including WebLogic Server, will most likely be rejected.
-
-### Use Helm chart from GitHub chart repository
-
-Add this repository to the Helm installation:
-
-```
-$ helm repo add weblogic-operator https://oracle.github.io/weblogic-kubernetes-operator/charts
-```
-
-Verify that the repository was added correctly:
-
-```
-$ helm repo list
-NAME           URL
-weblogic-operator    https://oracle.github.io/weblogic-kubernetes-operator/charts
-```
-
-Update with the latest information about charts from the chart repositories:
-
-```
-$ helm repo update
-```
-
-Install the operator from the repository:
-
-```
-$ helm install weblogic-operator/weblogic-operator --name weblogic-operator
-```
diff --git a/docs-source/content/developerguide/building.md b/docs-source/content/developerguide/building.md
@@ -22,7 +22,7 @@ Contributions must conform to [coding and formatting standards]({{< relref "/dev
 $ mvn fmt:format
 ```
 
-### Building Javadoc
+#### Building Javadoc
 
 To build the Javadoc for the operator, issue the following command:
 
@@ -32,7 +32,7 @@ $ mvn javadoc:javadoc
 
 The Javadoc is also available in the GitHub repository [here](https://oracle.github.io/weblogic-kubernetes-operator/apidocs/index.html).
 
-### Building the operator Docker image
+#### Building the operator Docker image
 
 Log in to the Docker Store so that you will be able to pull the base image and create the Docker image as follows.  These commands should be executed in the project root directory:
 
@@ -49,15 +49,15 @@ If you have not used the base image (`store/oracle/serverjre:8`) before, you wil
 
 We recommend that you use a tag other than `latest`, to make it easy to distinguish your image.  In the example above, the tag could be the GitHub ID of the developer.
 
-### Running the operator from an IDE
+#### Running the operator from an IDE
 
 The operator can be run from an IDE, which is useful for debugging.  In order to do so, the machine running the IDE must be configured with a Kubernetes configuration file in `~/.kube/config` or in a location pointed to by the `KUBECONFIG` environment variable.
 
 Configure the IDE to run the class `oracle.kubernetes.operator.Main`.
 
 You may need to create a directory called `/operator` on your machine.  Please be aware that the operator code is targeted to Linux, and although it will run fine on macOS, it will probably not run on other operating systems.  If you develop on another operating system, you should deploy the operator to a Kubernetes cluster and use remote debugging instead.
 
-### Running the operator in a Kubernetes cluster
+#### Running the operator in a Kubernetes cluster
 
 If you're not running Kubernetes on your development machine, you'll need to make the Docker image available to a registry visible to your Kubernetes cluster.  Either `docker push` the image to a private registry or upload your image to a machine running Docker and Kubernetes as follows:
 
diff --git a/docs-source/content/developerguide/requirements.md b/docs-source/content/developerguide/requirements.md
@@ -5,7 +5,7 @@ draft: false
 weight: 1
 ---
 
-In addition to the requirements listed in the [User Guide]({{< relref "/userguide/introduction/introduction.md#prerequisites" >}}), the following software is also required to obtain and build the operator:
+In addition to the requirements listed in the [User guide]({{< relref "/userguide/introduction/introduction.md#prerequisites" >}}), the following software is also required to obtain and build the operator:
 
 * Git (1.8 or later recommended)
 * Java Developer Kit (1.8u131 or later recommended; please use 1.8, tests will not work on 1.9 or later versions)
@@ -15,7 +15,7 @@ The operator is written primarily in Java, BASH shell scripts, and WLST scripts.
 
 Because the target runtime environment for the operator is Oracle Linux, no particular effort has been made to ensure the build or tests run on any other operating system.  Please be aware that Oracle will not provide support, or accept pull requests to add support, for other operating systems.
 
-### Obtaining the operator source code
+#### Obtaining the operator source code
 
 The operator source code is published on GitHub at https://github.com/oracle/weblogic-kubernetes-operator.  Developers may clone this repository to a local machine or, if desired, create a fork in their personal namespace and clone the fork.  Developers who are planning to submit a pull request are advised to create a fork.
 
diff --git a/docs-source/content/quickstart/create-domain.md b/docs-source/content/quickstart/create-domain.md
@@ -18,7 +18,7 @@ weight: 6
     `sample-domain1-weblogic-credentials`.
 
 1.	Create a new image with a domain home by running the [`create-domain`](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/create-domain.sh) script.
-Follow the directions in the [README](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/README.md) file,
+Follow the directions in the [sample]({{< relref "/samples/simple/domains/domain-home-in-image/_index.md" >}}),
 including:
 
     * Copying the sample `kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/create-domain-inputs.yaml` file and updating your copy with the `domainUID` (`sample-domain1`),
@@ -131,4 +131,10 @@ Depending on where your Kubernetes cluster is running, you may need to open fire
 {{% /notice %}}
 
 
-1.	To access the WLS Administration Console, edit the `my-inputs.yaml` file (assuming that you named your copy `my-inputs.yaml`) to set `exposedAdminNodePort: true`. Open a browser to `http://your.server.com:30701`. As in the previous step, substitute the Node IP address of the worker node for `your.server.com`.
+1.	To access the WLS Administration Console:
+
+    a. Edit the `my-inputs.yaml` file (assuming that you named your copy `my-inputs.yaml`) to set `exposedAdminNodePort: true`.
+
+    b. Open a browser to `http://your.server.com:30701`.
+
+    c. As in step 5, substitute the Node IP address of the worker node for `your.server.com`.
diff --git a/docs-source/content/quickstart/introduction.md b/docs-source/content/quickstart/introduction.md
@@ -14,9 +14,8 @@ refer to the [User guide]({{< relref "/userguide/_index.md" >}}).
 
 
 {{% notice warning %}}
-If you have an older version of the operator installed on your cluster, i.e. a 1.x version, or one of the 2.0 release 
-candidates, you must remove
-it before installing this version.  This includes the 2.0-rc1 version; it must be completely removed.
+If you have an older version of the operator installed on your cluster, for example, a 1.x version or one of the 2.0 release
+candidates, then you must remove it before installing this version.  This includes the 2.0-rc1 version; it must be completely removed.
 You should remove the deployment (for example, `kubectl delete deploy weblogic-operator -n your-namespace`) and the custom
 resource definition (for example, `kubectl delete crd domain`).  If you do not remove
 the custom resource definition you may see errors like this:
@@ -26,4 +25,4 @@ the API version in the data (weblogic.oracle/v2) does not match the expected API
 ```
 {{% /notice %}}
 
-{{% /expand %}}
+{{% /expand %}}
diff --git a/docs-source/content/reference/_index.md b/docs-source/content/reference/_index.md
@@ -2,12 +2,11 @@
 title = "Reference"
 date = 2019-02-22T16:16:39-05:00
 weight = 5
-chapter = true
 pre = "<b>5. </b>"
 +++
 
-### Chapter 5
 
-# Reference
 
-See the following API reference documentation.
+See the following reference documentation.
+
+{{% children style="h4" description="true" %}}
diff --git a/docs-source/content/reference/domain-resource.md b/docs-source/content/reference/domain-resource.md
@@ -0,0 +1,9 @@
+---
+title: "Domain resource"
+date: 2019-02-22T16:17:07-05:00
+draft: false
+weight: 3
+description: "Use this document to set up and configure your own domain resource"
+---
+
+View a domain resource reference document [here](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/docs/domains/Domain.md).
diff --git a/docs-source/content/reference/javadoc.md b/docs-source/content/reference/javadoc.md
@@ -3,6 +3,7 @@ title: "Javadoc"
 date: 2019-02-22T16:17:01-05:00
 draft: false
 weight: 1
+description: "Java API documentation"
 ---
 
 You can view the Java API documentation [here](https://oracle.github.io/weblogic-kubernetes-operator/apidocs/index.html).
diff --git a/docs-source/content/reference/swagger.md b/docs-source/content/reference/swagger.md
@@ -3,6 +3,7 @@ title: "Swagger"
 date: 2019-02-22T16:17:07-05:00
 draft: false
 weight: 2
+description: "Swagger REST API documentation"
 ---
 
 You can view the Swagger REST API documentation [here](https://oracle.github.io/weblogic-kubernetes-operator/swagger/index.html).
diff --git a/docs-source/content/release-notes.md b/docs-source/content/release-notes.md
@@ -4,7 +4,7 @@ date: 2019-03-15T11:25:28-04:00
 draft: false
 ---
 
-This document tracks recent changes to the operator, especially ones that introduce backward incompatibilities.
+### Recent changes
 
 | Date | Version | Introduces backward incompatibilities | Change |
 | --- | --- | --- | --- |
@@ -15,3 +15,9 @@ This document tracks recent changes to the operator, especially ones that introd
 | March 20, 2018 | v1.1 | yes | Several files and input parameters have been renamed.  This affects how operators and domains are created.  It also changes generated Kubernetes artifacts, therefore customers must recreate their operators and domains.
 | April 4, 2018 | v1.0 | yes | Many Kubernetes artifact names and labels have changed. Also, the names of generated YAML files for creating a domain's PV and PVC have changed.  Because of these changes, customers must recreate their operators and domains.
 | May 7, 2018 |   | no | Added support for dynamic clusters, the Apache HTTP Server, the Voyager Ingress Controller, and for PV in NFS storage for multi-node environments.
+
+### Known issues
+
+| Issue | Description |
+| --- | --- |
+| None currently |  |
diff --git a/docs-source/content/samples/simple/ingress/_index.md b/docs-source/content/samples/simple/ingress/_index.md
@@ -2,10 +2,9 @@
 title: "Ingress"
 date: 2019-02-23T17:32:31-05:00
 weight: 5
-description: "Lorem Ipsum."
+description: "Load balancer sample scripts."
 ---
 
-## Load balancer sample scripts
 
 The Oracle WebLogic Server Kubernetes Operator supports three load balancers: Traefik, Voyager, and Apache. We provide samples that demonstrate how to install and configure each one. The samples are located in following folders:
 
@@ -16,4 +15,6 @@ The Oracle WebLogic Server Kubernetes Operator supports three load balancers: Tr
 * [ingress-per-domain](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/charts/ingress-per-domain/README.md)
 * [apache-webtier](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/charts/apache-webtier/README.md)
 
-**Note**: The apache-webtier script contains a Helm chart that is used in the Apache samples.
+{{% notice note %}}
+The apache-webtier script contains a Helm chart that is used in the Apache samples.
+{{% /notice %}}
diff --git a/docs-source/content/security/_index.md b/docs-source/content/security/_index.md
@@ -2,12 +2,8 @@
 title = "Security"
 date = 2019-02-23T17:34:48-05:00
 weight = 6
-chapter = true
 pre = "<b>6. </b>"
 +++
 
-### Chapter 6
-
-# Security
 
 {{% children style="h4" description="true" %}}
diff --git a/docs-source/content/userguide/_index.md b/docs-source/content/userguide/_index.md
@@ -2,11 +2,10 @@
 title = "User Guide"
 date = 2019-02-22T15:27:48-05:00
 weight = 2
-chapter = true
 pre = "<b>2. </b>"
 +++
 
 
-# User Guide
-
 The User Guide provides detailed information about all aspects of using the operator.
+
+{{% children style="h4" description="true" %}}
diff --git a/docs-source/content/userguide/managing-domains/_index.md b/docs-source/content/userguide/managing-domains/_index.md
@@ -65,10 +65,10 @@ Please be aware of the following important considerations for WebLogic domains r
 
 * _Security Note:_ The `USER_MEM_ARGS` environment variable defaults to `-Djava.security.egd=file:/dev/./urandom` in all WebLogic Server pods and the WebLogic introspection job. It can be explicitly set to another value in your domain resource YAML file using the `env` attribute under the `serverPod` configuration.
 
-The following features are not certified or supported in this release:
+The following features are **not** certified or supported in this release:
 
-* Whole Server Migration
-* Consensus Leasing
+* Whole server migration
+* Consensus leasing
 * Node Manager (although it is used internally for the liveness probe and to start WebLogic Server instances)
 * Multicast
 * Multitenancy
diff --git a/docs-source/content/userguide/managing-domains/accessing-the-domain/wlst.md b/docs-source/content/userguide/managing-domains/accessing-the-domain/wlst.md
@@ -3,6 +3,7 @@ title: "Using WLST"
 date: 2019-02-23T17:39:19-05:00
 draft: false
 weight: 3
+description: "You can use the WebLogic Scripting Tool (WLST) to manage a domain running in Kubernetes."
 ---
 
 
diff --git a/docs-source/content/userguide/managing-domains/domain-in-image/base-images/_index.md b/docs-source/content/userguide/managing-domains/domain-in-image/base-images/_index.md
@@ -1,9 +1,9 @@
-+++
-title = "Base images"
-date = 2019-02-23T16:45:55-05:00
-weight = 1
-pre = "<b> </b>"
-+++
+---
+title: "Base images"
+date: 2019-02-23T16:45:55-05:00
+weight: 1
+description: "Creating or obtaining WebLogic Docker images."
+---
 
 #### Contents
 
diff --git a/docs-source/content/userguide/managing-domains/domain-lifecycle/_index.md b/docs-source/content/userguide/managing-domains/domain-lifecycle/_index.md
@@ -5,6 +5,6 @@ weight = 8
 pre = "<b> </b>"
 +++
 
-
-
 Learn how you can start, stop, restart, and scale the domain's servers.
+
+{{% children style="h4" description="true" %}}
diff --git a/docs-source/content/userguide/managing-domains/domain-lifecycle/restarting.md b/docs-source/content/userguide/managing-domains/domain-lifecycle/restarting.md
@@ -3,6 +3,7 @@ title: "Restarting"
 date: 2019-02-23T20:58:51-05:00
 draft: false
 weight: 2
+description: "This document describes when to restart servers in the Oracle WebLogic Server in Kubernetes environment."
 ---
 
 
diff --git a/docs-source/content/userguide/managing-domains/domain-lifecycle/scaling.md b/docs-source/content/userguide/managing-domains/domain-lifecycle/scaling.md
@@ -3,6 +3,7 @@ title: "Scaling"
 date: 2019-02-23T17:04:45-05:00
 draft: false
 weight: 3
+description: "The operator provides several ways to initiate scaling of WebLogic clusters."
 ---
 
 WebLogic Server supports two types of clustering configurations, configured and dynamic. Configured clusters are created by manually configuring each individual Managed Server instance. In dynamic clusters, the Managed Server configurations are generated from a single, shared template.  With dynamic clusters, when additional server capacity is needed, new server instances can be added to the cluster without having to manually configure them individually. Also, unlike configured clusters, scaling up of dynamic clusters is not restricted to the set of servers defined in the cluster but can be increased based on runtime demands. For more information on how to create, configure, and use dynamic clusters in WebLogic Server, see [Dynamic Clusters](https://docs.oracle.com/middleware/12213/wls/CLUST/dynamic_clusters.htm#CLUST678).
diff --git a/docs-source/content/userguide/managing-domains/domain-lifecycle/startup.md b/docs-source/content/userguide/managing-domains/domain-lifecycle/startup.md
@@ -3,7 +3,10 @@ title: "Startup and shutdown"
 date: 2019-02-23T17:04:41-05:00
 draft: false
 weight: 1
+description: "There are properties on the domain resource that specify which servers should be running
+and which servers should be restarted. To start, stop, or restart servers, modify these properties on the domain resource."
 ---
+
 #### Contents
 
 * [Starting and stopping servers](#starting-and-stopping-servers)
diff --git a/docs-source/content/userguide/managing-domains/domain-resource.md b/docs-source/content/userguide/managing-domains/domain-resource.md
@@ -8,13 +8,14 @@ pre = "<b> </b>"
 
 
 
-Use this document to set up and configure your own [domain resource](/weblogic-kubernetes-operator/domains/Domain.md) which can be used to configure your WLS domain. Then, you can use the domain resource to start the Kubernetes artifacts of the corresponding domain.
+Use this document to set up and configure your own [domain resource](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/docs/domains/Domain.md) which can be used to configure your WLS domain. Then, you can use the domain resource to start the Kubernetes artifacts of the corresponding domain.
 
 Swagger documentation is available [here](/weblogic-kubernetes-operator/swagger/index.html).
 
 #### Prerequisites
 
 The following prerequisites must be fulfilled before proceeding with the creation of the resource.
+
 * Make sure the WebLogic operator is running.
 * Create a Kubernetes namespace for the domain resource unless the intention is to use the default namespace.
 * Create the Kubernetes secrets `username` and `password` of the administrative account in the same Kubernetes namespace as the domain resource.
diff --git a/docs-source/content/userguide/managing-operators/_index.md b/docs-source/content/userguide/managing-operators/_index.md
@@ -14,7 +14,8 @@ Helm is a framework that helps you manage Kubernetes applications, and Helm char
 {{% expand "Click here to expand" %}}
 
 {{% notice warning %}}
-If you have an older version of the operator installed on your cluster, then you must remove it before installing this version. This includes the 2.0-rc1 version; it must be completely removed. You should remove the deployment (for example, `kubectl delete deploy weblogic-operator -n your-namespace`) and the custom
+If you have an older version of the operator installed on your cluster, for example, a 1.x version or one of the 2.0 release
+candidates, then you must remove it before installing this version. This includes the 2.0-rc1 version; it must be completely removed. You should remove the deployment (for example, `kubectl delete deploy weblogic-operator -n your-namespace`) and the custom
 resource definition (for example, `kubectl delete crd domain`).  If you do not remove
 the custom resource definition, then you might see errors like this:
 ```
@@ -23,10 +24,6 @@ the API version in the data (weblogic.oracle/v2) does not match the expected API
 ```
 {{% /notice %}}      
 
-{{% notice note %}}
-You should be able to upgrade from version 2.0-rc2 to 2.0 because there are no backward incompatible changes between these two releases.
-{{% /notice %}}
-
 {{% /expand %}}
 
 #### Install Helm and Tiller
diff --git a/docs-source/content/userguide/managing-operators/using-the-operator/_index.md b/docs-source/content/userguide/managing-operators/using-the-operator/_index.md
@@ -4,3 +4,5 @@ date = 2019-02-23T17:08:18-05:00
 weight = 2
 pre = "<b> </b>"
 +++
+
+{{% children style="h4" description="true" %}}
diff --git a/docs-source/content/userguide/overview/k8s-setup.md b/docs-source/content/userguide/overview/k8s-setup.md
@@ -35,7 +35,7 @@ Follow the basic steps from the  [Terraform Kubernetes installer for Oracle Clou
      oci = "<path_to_provider_binary>/terraform-provider-oci"
    }
    ```
-4.  Ensure that you have [kubectl][Kubectl] installed if you plan to interact with the cluster locally.
+4.  Ensure that you have [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed if you plan to interact with the cluster locally.
 
 #### Quick Start
 
@@ -438,6 +438,6 @@ Docker for Mac 18+ provides an [embedded Kubernetes environment](https://docs.do
     To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
     ```
 
-#### Important note about persistent volumes
-
-Docker for Mac has some restrictions on where you can place a directory that can be used as a `HostPath` for a persistent volume.  To keep it simple, place your directory somewhere under `/Users`.
+    #### Important note about persistent volumes
+  {{% notice warning %}} Docker for Mac has some restrictions on where you can place a directory that can be used as a `HostPath` for a persistent volume.  To keep it simple, place your directory somewhere under `/Users`.
+  {{% /notice %}}
diff --git a/docs-source/content/userguide/overview/prepare.md b/docs-source/content/userguide/overview/prepare.md
