Add ansible-doc text output (#36)

* Add ansible-doc text output handling.

* Add updated test vectors from Python project.

* Add changelog.

* Fix formatting.

changelogs/fragments/36-ansible-doc-text.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Add support for ansible-doc like text output (https://github.com/ansible-community/antsibull-docs-ts/pull/36)."

src/ansible-doc-text.spec.ts

@@ -0,0 +1,17 @@
+/*
+  Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+  SPDX-FileCopyrightText: Ansible Project
+  SPDX-License-Identifier: BSD-2-Clause
+*/
+
+import { toAnsibleDocText } from './ansible-doc-text';
+import { PartType } from './dom';
+
+describe('toRST tests', (): void => {
+  it('no paragraphs', (): void => {
+    expect(toAnsibleDocText([])).toBe('');
+  });
+  it('single paragraph with simple text', (): void => {
+    expect(toAnsibleDocText([[{ type: PartType.TEXT, text: 'test' }]])).toBe('test');
+  });
+});

src/ansible-doc-text.ts

@@ -0,0 +1,51 @@
+/*
+  Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+  SPDX-FileCopyrightText: Ansible Project
+  SPDX-License-Identifier: BSD-2-Clause
+*/
+
+import { AnsibleDocTextOptions, AllFormatOptions, mergeOpts, LinkProviders } from './opts';
+import { OptionNamePart, Paragraph, ReturnValuePart } from './dom';
+import { addToDestination } from './format';
+
+function formatOptionLike(part: OptionNamePart | ReturnValuePart): string {
+  let text = part.value === undefined ? `\`${part.name}'` : `\`${part.name}=${part.value}'`;
+  if (part.plugin) {
+    const plugin_suffix = ['role', 'module', 'playbook'].includes(part.plugin.type) ? '' : ' plugin';
+    let plugin = `${part.plugin.type}${plugin_suffix} ${part.plugin.fqcn}`;
+    if (part.plugin.type === 'role' && part.entrypoint !== undefined) {
+      plugin = `${plugin}, ${part.entrypoint} entrypoint`;
+    }
+    text = `${text} (of ${plugin})`;
+  }
+  return text;
+}
+
+const DEFAULT_FORMATTER: AllFormatOptions = {
+  formatError: (part) => `[[ERROR while parsing: ${part.message}]]`,
+  formatBold: (part) => `*${part.text}*`,
+  formatCode: (part) => `\`${part.text}'`,
+  formatHorizontalLine: () => '\n-------------\n',
+  formatItalic: (part) => `\`${part.text}'`,
+  formatLink: (part) => `${part.text} <${part.url}>`,
+  formatModule: (part) => `[${part.fqcn}]`,
+  formatRSTRef: (part) => part.text,
+  formatURL: (part) => part.url,
+  formatText: (part) => part.text,
+  formatEnvVariable: (part) => `\`${part.name}'`,
+  formatOptionName: (part) => formatOptionLike(part),
+  formatOptionValue: (part) => `\`${part.value}'`,
+  formatPlugin: (part) => `[${part.plugin.fqcn}]`,
+  formatReturnValue: (part) => formatOptionLike(part),
+};
+
+export function toAnsibleDocText(paragraphs: Paragraph[], opts?: AnsibleDocTextOptions): string {
+  const mergedOpts = mergeOpts(Object.assign({} as LinkProviders, opts), DEFAULT_FORMATTER);
+  const result: string[] = [];
+  for (const paragraph of paragraphs) {
+    const line: string[] = [];
+    addToDestination(line, paragraph, mergedOpts);
+    result.push(line.join(''));
+  }
+  return result.join('\n\n');
+}

src/index.ts

@@ -9,6 +9,7 @@ export { parse } from './parser';
 export * as dom from './dom';
 
 // Output
+export { toAnsibleDocText } from './ansible-doc-text';
 export { quoteHTML, toHTML } from './html';
 export { quoteMD, toMD } from './md';
 export { quoteRST, toRST } from './rst';

src/opts.ts

@@ -120,6 +120,8 @@ export interface MDOptions extends CommonExportOptions, CommonFormatOptions, Lin
 
 export interface RSTOptions extends CommonExportOptions, CommonFormatOptions {}
 
+export interface AnsibleDocTextOptions extends CommonExportOptions, CommonFormatOptions {}
+
 export function mergeOpts<T extends CommonFormatOptions>(options: T, fallback: AllFormatOptions): T & AllFormatOptions {
   /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
   const result: any = Object.assign({}, fallback, options);

src/vectors.spec.ts

@@ -12,6 +12,7 @@ import { parse } from './parser';
 import { toHTML } from './html';
 import { toMD } from './md';
 import { toRST } from './rst';
+import { toAnsibleDocText } from './ansible-doc-text';
 
 describe('vectors', (): void => {
   const data = readFileSync('test-vectors.yaml', 'utf8');
@@ -56,5 +57,12 @@ describe('vectors', (): void => {
         expect(toRST(parse(test_data.source, test_data.parse_opts), test_data.rst_opts)).toEqual(test_data.rst);
       });
     }
+    if (test_data.source !== undefined && test_data.ansible_doc_text !== undefined) {
+      it(`${test_name} (Ansible doc => ansible-doc text output)`, (): void => {
+        expect(
+          toAnsibleDocText(parse(test_data.source, test_data.parse_opts), test_data.ansible_doc_text_opts),
+        ).toEqual(test_data.ansible_doc_text);
+      });
+    }
   }
 });