Add support for semantic markup (#1)

* Revert "Remove semantic markup definitions/options."

This reverts commit b5d3365.

* Add missing marker.

* Implement argument parsing with escaping.

* Add basic 'is plugin type' test.

* Implement first batch of semantic markup commands (the easy ones).

* Implement O() and RV().

* Fix P() parsing.

* Support serialization.

* Add changelog fragment.

* Simplify MarkDown formatting (remove CSS classes).

Author: felixfontein

.prettierignore

@@ -6,3 +6,4 @@
 /changelogs/changelog.yaml
 /changelogs/fragments/*
 /dist/
+/test-vectors.yaml

changelogs/fragments/1-semantic-markup.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Add support for semantic markup (https://github.com/ansible-community/antsibull-docs-ts/pull/1)."

src/ansible.ts

@@ -7,3 +7,8 @@
 export function isFQCN(input: string): boolean {
   return input.match(/^[a-z0-9_]+\.[a-z0-9_]+(?:\.[a-z0-9_]+)+$/) !== null;
 }
+
+export function isPluginType(input: string): boolean {
+  /* We do not want to hard-code a list of valid plugin types that might be inaccurate, so we simply check whether this is a valid kind of Python identifier usually used for plugin types. If ansible-core ever adds one with digits, we'll have to update this. */
+  return /^[a-z_]+$/.test(input);
+}

src/html.ts

@@ -5,12 +5,54 @@
 */
 
 import { HTMLOptions } from './opts';
-import { PartType, Paragraph } from './parser';
+import { OptionNamePart, PartType, Paragraph, ReturnValuePart } from './parser';
 
 export function quoteHTML(text: string): string {
   return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
+function formatOptionLike(
+  part: OptionNamePart | ReturnValuePart,
+  what: 'option' | 'retval',
+  opts: HTMLOptions,
+): string {
+  let url: string | undefined;
+  if (part.plugin && opts.pluginOptionLikeLink) {
+    url = opts.pluginOptionLikeLink(part.plugin, what, part.link, part.plugin === opts.current_plugin);
+  }
+  let link_start = '';
+  let link_end = '';
+  if (url) {
+    link_start = `<a class="reference internal" href="${quoteHTML(
+      encodeURI(url),
+    )}"><span class="std std-ref"><span class="pre">`;
+    link_end = '</span></span></a>';
+  }
+  let cls: string;
+  let strong_start = '';
+  let strong_end = '';
+  if (what === 'option') {
+    if (part.value === undefined) {
+      cls = 'ansible-option';
+      strong_start = '<strong>';
+      strong_end = '</strong>';
+    } else {
+      cls = 'ansible-option-value';
+    }
+  } else {
+    cls = 'ansible-return-value';
+  }
+  let text: string;
+  if (part.value === undefined) {
+    text = part.name;
+  } else {
+    text = `${part.name}=${part.value}`;
+  }
+  return `<code class="${cls} literal notranslate">${strong_start}${link_start}${quoteHTML(
+    text,
+  )}${link_end}${strong_end}</code>`;
+}
+
 export function toHTML(paragraphs: Paragraph[], opts?: HTMLOptions): string {
   if (!opts) {
     opts = {};
@@ -59,6 +101,30 @@ export function toHTML(paragraphs: Paragraph[], opts?: HTMLOptions): string {
         case PartType.TEXT:
           result.push(quoteHTML(part.text));
           break;
+        case PartType.ENV_VARIABLE:
+          result.push(`<code class="xref std std-envvar literal notranslate">${quoteHTML(part.name)}</code>`);
+          break;
+        case PartType.OPTION_NAME:
+          result.push(formatOptionLike(part, 'option', opts));
+          break;
+        case PartType.OPTION_VALUE:
+          result.push(`<code class="ansible-value literal notranslate">${quoteHTML(part.value)}</code>`);
+          break;
+        case PartType.PLUGIN: {
+          let url: string | undefined;
+          if (opts.pluginLink) {
+            url = opts.pluginLink(part.plugin);
+          }
+          if (url) {
+            result.push(`<a href='${url}' class='module'>${quoteHTML(part.plugin.fqcn)}</a>`);
+          } else {
+            result.push(`<span class='module'>${quoteHTML(part.plugin.fqcn)}</span>`);
+          }
+          break;
+        }
+        case PartType.RETURN_VALUE:
+          result.push(formatOptionLike(part, 'retval', opts));
+          break;
       }
     }
     result.push('</p>');

src/md.ts

@@ -7,12 +7,40 @@
 // CommonMark spec: https://spec.commonmark.org/current/
 
 import { MDOptions } from './opts';
-import { PartType, Paragraph } from './parser';
+import { OptionNamePart, PartType, Paragraph, ReturnValuePart } from './parser';
 
 export function quoteMD(text: string): string {
   return text.replace(/([!"#$%&'()*+,:;<=>?@[\\\]^_`{|}~-])/g, '\\$1');
 }
 
+function formatOptionLike(part: OptionNamePart | ReturnValuePart, what: 'option' | 'retval', opts: MDOptions): string {
+  let url: string | undefined;
+  if (part.plugin && opts.pluginOptionLikeLink) {
+    url = opts.pluginOptionLikeLink(part.plugin, what, part.link, part.plugin === opts.current_plugin);
+  }
+  let link_start = '';
+  let link_end = '';
+  if (url) {
+    link_start = `<a href="${quoteMD(encodeURI(url))}">`;
+    link_end = '</a>';
+  }
+  let strong_start = '';
+  let strong_end = '';
+  if (what === 'option') {
+    if (part.value === undefined) {
+      strong_start = '<strong>';
+      strong_end = '</strong>';
+    }
+  }
+  let text: string;
+  if (part.value === undefined) {
+    text = part.name;
+  } else {
+    text = `${part.name}=${part.value}`;
+  }
+  return `<code>${strong_start}${link_start}${quoteMD(text)}${link_end}${strong_end}</code>`;
+}
+
 export function toMD(paragraphs: Paragraph[], opts?: MDOptions): string {
   if (!opts) {
     opts = {};
@@ -61,6 +89,30 @@ export function toMD(paragraphs: Paragraph[], opts?: MDOptions): string {
         case PartType.TEXT:
           line.push(quoteMD(part.text));
           break;
+        case PartType.ENV_VARIABLE:
+          line.push(`<code>${quoteMD(part.name)}</code>`);
+          break;
+        case PartType.OPTION_NAME:
+          line.push(formatOptionLike(part, 'option', opts));
+          break;
+        case PartType.OPTION_VALUE:
+          line.push(`<code>${quoteMD(part.value)}</code>`);
+          break;
+        case PartType.PLUGIN: {
+          let url: string | undefined;
+          if (opts.pluginLink) {
+            url = opts.pluginLink(part.plugin);
+          }
+          if (url) {
+            line.push(`[${quoteMD(part.plugin.fqcn)}](${quoteMD(encodeURI(url))})`);
+          } else {
+            line.push(`${quoteMD(part.plugin.fqcn)}`);
+          }
+          break;
+        }
+        case PartType.RETURN_VALUE:
+          line.push(formatOptionLike(part, 'retval', opts));
+          break;
       }
     }
     if (!line.length) {

src/opts.ts

@@ -21,29 +21,44 @@ export interface PluginIdentifier {
   type: string;
 }
 
-/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
 export interface ParsingOptions extends ErrorHandlingOptions {
   /** Should be provided if parsing documentation of a plugin/module/role. */
   current_plugin?: PluginIdentifier;
+
+  /** If set to 'true', only 'classic' Ansible docs markup is accepted. */
+  only_classic_markup?: boolean;
 }
 
-/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
 interface CommonExportOptions extends ErrorHandlingOptions {
   /** Should be provided if rendering documentation for a plugin/module/role. */
   current_plugin?: PluginIdentifier;
 }
 
-/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
 export interface HTMLOptions extends CommonExportOptions {
   /** Provides a link to a plugin. */
   pluginLink?: (plugin: PluginIdentifier) => string | undefined;
-}
 
-/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
-export interface RSTOptions extends CommonExportOptions {}
+  /** Provides a link to a plugin's option or return value. */
+  pluginOptionLikeLink?: (
+    plugin: PluginIdentifier,
+    what: 'option' | 'retval',
+    name: string[],
+    current_plugin: boolean,
+  ) => string | undefined;
+}
 
-/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
 export interface MDOptions extends CommonExportOptions {
   /** Provides a link to a plugin. */
   pluginLink?: (plugin: PluginIdentifier) => string | undefined;
+
+  /** Provides a link to a plugin's option or return value. */
+  pluginOptionLikeLink?: (
+    plugin: PluginIdentifier,
+    what: 'option' | 'retval',
+    name: string[],
+    current_plugin: boolean,
+  ) => string | undefined;
 }
+
+/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
+export interface RSTOptions extends CommonExportOptions {}