ROX-15394: Add markdown for parameter help formatting (#1065)

stackrox · Nov 15, 2023 · e35fc5d · e35fc5d
1 parent c0cbab3
commit e35fc5d
Show file tree

Hide file tree

Showing 7 changed files with 627 additions and 36 deletions.
diff --git a/chart/infra-server/static/flavors.yaml b/chart/infra-server/static/flavors.yaml
@@ -139,7 +139,8 @@
       value: ""
       kind: optional
       help: |
-        e.g. 1.19.12-gke.2100. Use 'gcloud container get-server-config --zone=us-central1 --project acs-team-temp-dev' to see all versions.
+        e.g. 1.19.12-gke.2100. Use `gcloud container get-server-config
+        --zone=us-central1 --project acs-team-temp-dev` to see all versions.
 
     - name: pod-security-policy
       description: Enable pod security policy
@@ -151,7 +152,9 @@
       description: The GCP image type to use for the cluster
       value: ""
       kind: optional
-      help: "List of image types: https://cloud.google.com/kubernetes-engine/docs/concepts/node-images"
+      help: |
+        List of image types:
+        [node-images](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images)
 
     - name: gcp-zone
       description: The zone in GCP to delete the cluster from
@@ -255,11 +258,23 @@
       value: ocp/stable
       kind: optional
       help: |
-        The latest stable Red Hat enterprise OCP releases can be found at https://mirror.openshift.com/pub/openshift-v4/clients/ocp/.
-        For officially released OCP versions, use the path to one of the stable releases, e.g., ocp/stable-4.
-        Dev preview Red Hat enterprise OCP builds can be found at https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp-dev-preview/.
-        For dev preview OCP versions, use the path to one of the dev preview releases, e.g., ocp-dev-preview/latest.
-        Opensource OKD releases are at https://github.com/openshift/okd/releases.
+        ## Stable OCP
+
+        The latest stable Red Hat enterprise OCP releases can be found at
+        [clients/ocp/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp/). For
+        officially released OCP versions, use the path to one of the stable
+        releases, e.g., ocp/stable-4.
+
+        ## Dev Preview OCP
+
+        Dev preview Red Hat enterprise OCP builds can be found at
+        [clients/ocp-dev-preview/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp-dev-preview/).
+        For dev preview OCP versions, use the path to one of the dev preview
+        releases, e.g., ocp-dev-preview/latest.
+
+        ## Opensource OKD
+
+        Opensource OKD releases are at [okd/releases](https://github.com/openshift/okd/releases).
         For OKD, use the release tag, e.g., 4.7.0-0.okd-2021-02-25-144700.
 
     - name: pull-secret
@@ -268,7 +283,7 @@
       fromFile: true
       help: |
         Use this if you want to associate this cluster with a particular cloud.redhat.com account.
-        Get the pull secret from: https://cloud.redhat.com/openshift/install/pull-secret
+        Get the pull secret from: [cloud.redhat.com](https://cloud.redhat.com/openshift/install/pull-secret)
         You might do this for access to OpenShift Cluster Manager for example.
         By default an infra automation account is used.
 
@@ -377,11 +392,23 @@
       value: ocp/stable
       kind: optional
       help: |
-        The latest stable Red Hat enterprise OCP releases can be found at https://mirror.openshift.com/pub/openshift-v4/clients/ocp/.
-        For officially released OCP versions, use the path to one of the stable releases, e.g., ocp/stable-4.
-        Dev preview Red Hat enterprise OCP builds can be found at https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp-dev-preview/.
-        For dev preview OCP versions, use the path to one of the dev preview releases, e.g., ocp-dev-preview/latest.
-        Opensource OKD releases are at https://github.com/openshift/okd/releases.
+        ## Stable OCP
+
+        The latest stable Red Hat enterprise OCP releases can be found at
+        [clients/ocp/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp/). For
+        officially released OCP versions, use the path to one of the stable
+        releases, e.g., ocp/stable-4.
+
+        ## Dev Preview OCP
+
+        Dev preview Red Hat enterprise OCP builds can be found at
+        [clients/ocp-dev-preview/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp-dev-preview/).
+        For dev preview OCP versions, use the path to one of the dev preview
+        releases, e.g., ocp-dev-preview/latest.
+
+        ## Opensource OKD
+
+        Opensource OKD releases are at [okd/releases](https://github.com/openshift/okd/releases).
         For OKD, use the release tag, e.g., 4.7.0-0.okd-2021-02-25-144700.
 
     - name: image-registry
@@ -492,11 +519,23 @@
       value: ocp/stable
       kind: optional
       help: |
-        The latest stable Red Hat enterprise OCP releases can be found at https://mirror.openshift.com/pub/openshift-v4/clients/ocp/.
-        For officially released OCP versions, use the path to one of the stable releases, e.g., ocp/stable-4.
-        Dev preview Red Hat enterprise OCP builds can be found at https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp-dev-preview/.
-        For dev preview OCP versions, use the path to one of the dev preview releases, e.g., ocp-dev-preview/latest.
-        Opensource OKD releases are at https://github.com/openshift/okd/releases.
+        ## Stable OCP
+
+        The latest stable Red Hat enterprise OCP releases can be found at
+        [clients/ocp/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp/). For
+        officially released OCP versions, use the path to one of the stable
+        releases, e.g., ocp/stable-4.
+
+        ## Dev Preview OCP
+
+        Dev preview Red Hat enterprise OCP builds can be found at
+        [clients/ocp-dev-preview/](https://mirror.openshift.com/pub/openshift-v4/clients/ocp-dev-preview/).
+        For dev preview OCP versions, use the path to one of the dev preview
+        releases, e.g., ocp-dev-preview/latest.
+
+        ## Opensource OKD
+
+        Opensource OKD releases are at [okd/releases](https://github.com/openshift/okd/releases).
         For OKD, use the release tag, e.g., 4.7.0-0.okd-2021-02-25-144700.
 
     - name: pull-secret
@@ -505,7 +544,7 @@
       fromFile: true
       help: |
         Use this if you want to associate this cluster with a particular cloud.redhat.com account.
-        Get the pull secret from: https://cloud.redhat.com/openshift/install/pull-secret
+        Get the pull secret from: [cloud.redhat.com](https://cloud.redhat.com/openshift/install/pull-secret)
         You might do this for access to OpenShift Cluster Manager for example.
         By default an infra automation account is used.
 
@@ -776,9 +815,13 @@
       kind: optional
 
     - name: machine-type
-      description: node machine type (https://aws.amazon.com/ec2/instance-types/, https://instances.vantage.sh/)
+      description: node machine type
       value: m5.2xlarge
       kind: optional
+      help: |
+        For options see
+        [https://aws.amazon.com/ec2/instance-types/](https://aws.amazon.com/ec2/instance-types/) and
+        [https://instances.vantage.sh/](https://instances.vantage.sh/)
 
   artifacts:
     - name: kubeconfig
@@ -819,9 +862,15 @@
       kind: optional
 
     - name: machine-type
-      description: node machine type (custom-96-393216 custom-96-196608 custom-72-147456 custom-64-262144 custom-48-98304 custom-48-196608 custom-36-73728 custom-32-131072 custom-4-32768-ext custom-4-16384 custom-8-32768 custom-8-16384 custom-8-65536-ext custom-16-131072-ext custom-16-32768 custom-16-65536)
+      description: node machine type
       value: custom-8-32768
       kind: optional
+      help: |
+        Options are: custom-96-393216 custom-96-196608 custom-72-147456
+        custom-64-262144 custom-48-98304 custom-48-196608 custom-36-73728
+        custom-32-131072 custom-4-32768-ext custom-4-16384 custom-8-32768
+        custom-8-16384 custom-8-65536-ext custom-16-131072-ext custom-16-32768
+        custom-16-65536
 
   artifacts:
     - name: kubeconfig

diff --git a/ui/package.json b/ui/package.json
@@ -35,6 +35,7 @@
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
     "react-feather": "^2.0.9",
+    "react-markdown": "^8.0.0",
     "react-router-dom": "^6.14.1",
     "react-spinners": "^0.13.8",
     "use-clipboard-copy": "^0.2.0",

diff --git a/ui/src/components/forms/FileUploadFormField.tsx b/ui/src/components/forms/FileUploadFormField.tsx
@@ -1,4 +1,4 @@
-import React, { ReactElement } from 'react';
+import React, { ReactElement, ReactNode } from 'react';
 import { useField } from 'formik';
 import { FormGroup, Popover, FileUpload, ValidatedOptions } from '@patternfly/react-core';
 import { HelpIcon } from '@patternfly/react-icons';
@@ -8,15 +8,15 @@ type Props = {
   id?: string;
   required?: boolean;
   label: string;
-  helperText?: string;
+  helper?: ReactNode;
 };
 
 export default function FileUploadFormField({
   name,
   id = `file-input-${name}`,
   required = false,
   label,
-  helperText = '',
+  helper,
 }: Props): ReactElement {
   const [field, meta, helpers] = useField(name);
   const [filename, setFilename] = React.useState('');
@@ -52,8 +52,8 @@ export default function FileUploadFormField({
       fieldId={id}
       isRequired={required}
       labelIcon={
-        helperText ? (
-          <Popover bodyContent={<div>{helperText}</div>}>
+        helper ? (
+          <Popover bodyContent={helper}>
             <button
               type="button"
               aria-label={`Help for ${name}`}

diff --git a/ui/src/components/forms/TextFormField.tsx b/ui/src/components/forms/TextFormField.tsx
@@ -1,4 +1,4 @@
-import React, { ReactElement } from 'react';
+import React, { ReactElement, ReactNode } from 'react';
 import { useField } from 'formik';
 import { FormGroup, Popover, TextInput, ValidatedOptions } from '@patternfly/react-core';
 import { HelpIcon } from '@patternfly/react-icons';
@@ -9,7 +9,7 @@ type Props = {
   required?: boolean;
   label: string;
   placeholder?: string;
-  helperText?: string;
+  helper?: ReactNode;
   disabled?: boolean;
 };
 
@@ -19,7 +19,7 @@ export default function TextFormField({
   required = false,
   label,
   placeholder = '',
-  helperText = '',
+  helper,
   disabled = false,
 }: Props): ReactElement {
   const [field, meta] = useField(name);
@@ -34,8 +34,8 @@ export default function TextFormField({
       fieldId={id}
       isRequired={required}
       labelIcon={
-        helperText ? (
-          <Popover bodyContent={<div>{helperText}</div>}>
+        helper ? (
+          <Popover bodyContent={helper} className="form-help">
             <button
               type="button"
               aria-label={`Help for ${name}`}

diff --git a/ui/src/containers/LaunchClusterPage/ClusterForm.tsx b/ui/src/containers/LaunchClusterPage/ClusterForm.tsx
@@ -13,6 +13,7 @@ import * as yup from 'yup';
 import { mapValues } from 'lodash';
 import { ClipLoader } from 'react-spinners';
 import { UploadCloud } from 'react-feather';
+import Markdown from 'react-markdown';
 
 import { ClusterServiceApi, V1Parameter } from 'generated/client';
 import configuration from 'client/configuration';
@@ -124,12 +125,17 @@ function ParameterFormField(props: {
 
   const required = !parameter.Optional;
 
+  let helper;
+  if (parameter.Help || helpByParameterName(parameter.Name)) {
+    helper = <Markdown>{parameter.Help || helpByParameterName(parameter.Name)}</Markdown>;
+  }
+
   if (parameter.FromFile) {
     return (
       <FileUploadFormField
         name={`Parameters.${parameter.Name}`}
         label={getFormLabelFromParameter(parameter)}
-        helperText={parameter.Help}
+        helper={helper}
         required={required}
       />
     );
@@ -141,7 +147,7 @@ function ParameterFormField(props: {
         <TextFormField
           name={`Parameters.${parameter.Name}`}
           label={getFormLabelFromParameter(parameter)}
-          helperText={parameter.Help || helpByParameterName(parameter.Name)}
+          helper={helper}
           required={required}
         />
       );

diff --git a/ui/src/infra.css b/ui/src/infra.css
@@ -49,3 +49,35 @@ a > .pf-c-panel > .pf-c-panel__header {
   font-weight: var(--pf-global--FontWeight--bold);
   font-size: var(--pf-global--FontSize--lg);
 }
+
+/* Form help popovers - rendered with react-markdown */
+
+/* #, ##, ### */
+.form-help h1,
+h2,
+h3 {
+  font-weight: var(--pf-global--FontWeight--bold);
+  margin-bottom: var(--pf-global--spacer--sm);
+}
+.form-help h1 {
+  font-size: var(--pf-global--FontSize--xl);
+}
+.form-help h2 {
+  font-size: var(--pf-global--FontSize--lg);
+}
+.form-help h3 {
+  font-size: var(--pf-global--FontSize--md);
+}
+
+/* A text block */
+.form-help p {
+  margin-bottom: var(--pf-global--spacer--lg);
+}
+
+/* [link](url) */
+.form-help a {
+  color: var(--pf-global--link--Color);
+}
+.form-help a:visited {
+  color: var(--pf-global--link--Color--visited);
+}