Docs - render object choices (#4442)

* RenderPluginDoc - support `choices` as an object previously, `choices` was a list of options, now it can also be an object of options: description, where description can be a string or an array of strings No-Issue * PAUSED: Use `git resume` to continue working. [skip ci] * Choice, Legend - render a monospace choice name, and a potentially multiline description * also fix docs error rendering * Update src/components/render-plugin-doc/render-plugin-doc.tsx Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]> (cherry picked from commit 269af3f)
ansible · Nov 5, 2023 · 7f0d1ce · 7f0d1ce
1 parent e3d450a
commit 7f0d1ce
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 15 deletions.
diff --git a/src/components/render-plugin-doc/render-plugin-doc.tsx b/src/components/render-plugin-doc/render-plugin-doc.tsx
@@ -1,5 +1,6 @@
+import { Trans, t } from '@lingui/macro';
 import { dom, parse } from 'antsibull-docs';
-import React from 'react';
+import React, { ReactNode } from 'react';
 import {
   PluginContentType,
   PluginDoc,
@@ -31,6 +32,18 @@ interface IProps {
   renderWarning: (text: string) => React.ReactElement;
 }
 
+function Choice({ children }: { children: ReactNode }) {
+  return <pre style={{ display: 'inline-block' }}>{children}</pre>;
+}
+
+function Legend({ children }: { children: ReactNode }) {
+  return (
+    <div style={{ display: 'inline-block', verticalAlign: 'top' }}>
+      {children}
+    </div>
+  );
+}
+
 export class RenderPluginDoc extends React.Component<IProps, IState> {
   subOptionsMaxDepth: number;
   returnContainMaxDepth: number;
@@ -644,47 +657,86 @@ export class RenderPluginDoc extends React.Component<IProps, IState> {
     );
   }
 
+  private renderLegend(legend) {
+    if (!legend) {
+      return null;
+    }
+
+    if (!Array.isArray(legend)) {
+      legend = [legend];
+    }
+
+    return (
+      <>
+        {': '}
+        <Legend>
+          {legend.map((d, i) => (
+            <>
+              {i ? <br /> : null}
+              {this.applyDocFormatters(d)}
+            </>
+          ))}
+        </Legend>
+      </>
+    );
+  }
+
   private renderChoices(option) {
-    let choices, defaul;
+    let choices,
+      defaultChoice,
+      legends = {};
 
     if (option['type'] === 'bool') {
       choices = ['true', 'false'];
+
       if (option['default'] === true) {
-        defaul = 'true';
+        defaultChoice = 'true';
       } else if (option['default'] === false) {
-        defaul = 'false';
+        defaultChoice = 'false';
       }
     } else {
       choices = option['choices'] || [];
-      defaul = option['default'];
+      defaultChoice = option['default'];
+    }
+
+    if (typeof choices === 'object' && !Array.isArray(choices)) {
+      legends = choices;
+      choices = Object.keys(choices);
     }
 
     return (
-      <React.Fragment>
+      <>
         {choices && Array.isArray(choices) && choices.length !== 0 ? (
           <div>
-            <span className='option-name'>Choices: </span>
+            <span className='option-name'>
+              <Trans>Choices: </Trans>
+            </span>
             <ul>
               {choices.map((c, i) => (
                 <li key={i}>
-                  {c === defaul ? (
-                    <span className='blue'>{c} &nbsp;&larr;</span>
+                  {c === defaultChoice ? (
+                    <span className='blue' title={t`default`}>
+                      <Choice>{c}</Choice> &nbsp;&larr;
+                    </span>
                   ) : (
-                    c
+                    <Choice>{c}</Choice>
                   )}
+                  {this.renderLegend(legends[c])}
                 </li>
               ))}
             </ul>
           </div>
         ) : null}
 
-        {defaul && !choices.includes(defaul) ? (
+        {defaultChoice !== undefined && !choices.includes(defaultChoice) ? (
           <span>
-            <span className='option-name'>Default: </span>
-            <span className='blue'>{defaul}</span>
+            <span className='option-name'>
+              <Trans>Default: </Trans>
+            </span>
+            <span className='blue'>{defaultChoice}</span>
           </span>
         ) : null}
-      </React.Fragment>
+      </>
     );
   }
 

diff --git a/src/containers/collection-detail/collection-docs.tsx b/src/containers/collection-detail/collection-docs.tsx
@@ -155,7 +155,7 @@ class CollectionDocs extends React.Component<RouteProps, IBaseCollectionState> {
             />
 
             <div
-              className='body hub-docs-content pf-c-content'
+              className='body hub-docs-content pf-c-content hub-content-alert-fix'
               ref={this.docsRef}
             >
               {displayHTML || pluginData ? (