antsibull-docs - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

dist/cjs/parser.js

@@ -270,2 +270,3 @@ "use strict";
                 result.push(command.process(args, opts, source));
+                /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
             }
@@ -272,0 +273,0 @@ catch (exc) {

dist/cjs/rst.js

@@ -22,3 +22,3 @@ "use strict";
 exports.quoteRST = quoteRST;
-function formatOptionLike(part, role) {
+function formatAntsibullOptionLike(part, role) {
     const result = [];
@@ -42,2 +42,26 @@ if (part.plugin) {
 }
+function formatPlainOptionLike(part) {
+    const plugin = [];
+    if (part.plugin) {
+        plugin.push(part.plugin.type);
+        if (!['module', 'role', 'playbook'].includes(part.plugin.type)) {
+            plugin.push(' plugin');
+        }
+        plugin.push(` :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\``);
+    }
+    if (part.entrypoint !== undefined) {
+        if (plugin.length) {
+            plugin.push(', ');
+        }
+        plugin.push('entrypoint ');
+        plugin.push(quoteRST(part.entrypoint, true));
+    }
+    let value = part.name;
+    if (part.value !== undefined) {
+        value = `${value}=${part.value}`;
+    }
+    const pluginText = plugin.length ? ` (of ${plugin.join('')})` : '';
+    const mainText = `:literal:\`${quoteRST(value, true, true)}\``;
+    return `\\ ${mainText}${pluginText}\\ `;
+}
 const DEFAULT_FORMATTER = {
@@ -55,9 +79,28 @@ formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
     formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
-    formatOptionName: (part) => formatOptionLike(part, 'ansopt'),
+    formatOptionName: (part) => formatAntsibullOptionLike(part, 'ansopt'),
     formatOptionValue: (part) => `\\ :ansval:\`${quoteRST(part.value, true, true)}\`\\ `,
     formatPlugin: (part) => `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
-    formatReturnValue: (part) => formatOptionLike(part, 'ansretval'),
+    formatReturnValue: (part) => formatAntsibullOptionLike(part, 'ansretval'),
 };
+const PLAIN_FORMATTER = {
+    formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
+    formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatHorizontalLine: () => '\n\n------------\n\n',
+    formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatLink: (part) => `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `,
+    formatModule: (part) => `\\ :ref:\`${quoteRST(part.fqcn)} <ansible_collections.${part.fqcn}_module>\`\\ `,
+    formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text)} <${part.ref}>\`\\ `,
+    formatURL: (part) => `\\ ${encodeURI(part.url)}\\ `,
+    formatText: (part) => quoteRST(part.text),
+    formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
+    formatOptionName: (part) => formatPlainOptionLike(part),
+    formatOptionValue: (part) => `\\ :literal:\`${quoteRST(part.value, true, true)}\`\\ `,
+    formatPlugin: (part) => `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
+    formatReturnValue: (part) => formatPlainOptionLike(part),
+};
 function toRST(paragraphs, opts) {
-    const mergedOpts = (0, opts_1.mergeOpts)(Object.assign({}, opts), DEFAULT_FORMATTER);
+    opts = opts !== null && opts !== void 0 ? opts : {};
+    const style = opts.style || 'antsibull-docs';
+    const mergedOpts = (0, opts_1.mergeOpts)(opts, style === 'antsibull-docs' ? DEFAULT_FORMATTER : PLAIN_FORMATTER);
     const result = [];
@@ -64,0 +107,0 @@ for (const paragraph of paragraphs) {

dist/esm/opts.d.ts

@@ -84,2 +84,5 @@ import { TextPart, ItalicPart, BoldPart, ModulePart, PluginPart, URLPart, LinkPart, RSTRefPart, CodePart, OptionNamePart, OptionValuePart, EnvVariablePart, ReturnValuePart, HorizontalLinePart, ErrorPart } from './dom';
 export interface RSTOptions extends CommonExportOptions, CommonFormatOptions {
+    /** Whether the RST should be formatted as in antsibull-docs (for use with Sphinx and the
+        sphinx_antsibull_ext extension) or with plain RST. Default: 'antsibull-docs'. */
+    style?: 'antsibull-docs' | 'plain';
 }
@@ -86,0 +89,0 @@ export interface AnsibleDocTextOptions extends CommonExportOptions, CommonFormatOptions {

dist/esm/parser.js

@@ -265,2 +265,3 @@ /*
                 result.push(command.process(args, opts, source));
+                /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
             }
@@ -267,0 +268,0 @@ catch (exc) {

dist/esm/rst.js

@@ -18,3 +18,3 @@ /*
 }
-function formatOptionLike(part, role) {
+function formatAntsibullOptionLike(part, role) {
     const result = [];
@@ -38,2 +38,26 @@ if (part.plugin) {
 }
+function formatPlainOptionLike(part) {
+    const plugin = [];
+    if (part.plugin) {
+        plugin.push(part.plugin.type);
+        if (!['module', 'role', 'playbook'].includes(part.plugin.type)) {
+            plugin.push(' plugin');
+        }
+        plugin.push(` :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\``);
+    }
+    if (part.entrypoint !== undefined) {
+        if (plugin.length) {
+            plugin.push(', ');
+        }
+        plugin.push('entrypoint ');
+        plugin.push(quoteRST(part.entrypoint, true));
+    }
+    let value = part.name;
+    if (part.value !== undefined) {
+        value = `${value}=${part.value}`;
+    }
+    const pluginText = plugin.length ? ` (of ${plugin.join('')})` : '';
+    const mainText = `:literal:\`${quoteRST(value, true, true)}\``;
+    return `\\ ${mainText}${pluginText}\\ `;
+}
 const DEFAULT_FORMATTER = {
@@ -51,9 +75,28 @@ formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
     formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
-    formatOptionName: (part) => formatOptionLike(part, 'ansopt'),
+    formatOptionName: (part) => formatAntsibullOptionLike(part, 'ansopt'),
     formatOptionValue: (part) => `\\ :ansval:\`${quoteRST(part.value, true, true)}\`\\ `,
     formatPlugin: (part) => `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
-    formatReturnValue: (part) => formatOptionLike(part, 'ansretval'),
+    formatReturnValue: (part) => formatAntsibullOptionLike(part, 'ansretval'),
 };
+const PLAIN_FORMATTER = {
+    formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
+    formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatHorizontalLine: () => '\n\n------------\n\n',
+    formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true)}\`\\ `,
+    formatLink: (part) => `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `,
+    formatModule: (part) => `\\ :ref:\`${quoteRST(part.fqcn)} <ansible_collections.${part.fqcn}_module>\`\\ `,
+    formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text)} <${part.ref}>\`\\ `,
+    formatURL: (part) => `\\ ${encodeURI(part.url)}\\ `,
+    formatText: (part) => quoteRST(part.text),
+    formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
+    formatOptionName: (part) => formatPlainOptionLike(part),
+    formatOptionValue: (part) => `\\ :literal:\`${quoteRST(part.value, true, true)}\`\\ `,
+    formatPlugin: (part) => `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
+    formatReturnValue: (part) => formatPlainOptionLike(part),
+};
 export function toRST(paragraphs, opts) {
-    const mergedOpts = mergeOpts(Object.assign({}, opts), DEFAULT_FORMATTER);
+    opts = opts !== null && opts !== void 0 ? opts : {};
+    const style = opts.style || 'antsibull-docs';
+    const mergedOpts = mergeOpts(opts, style === 'antsibull-docs' ? DEFAULT_FORMATTER : PLAIN_FORMATTER);
     const result = [];
@@ -60,0 +103,0 @@ for (const paragraph of paragraphs) {

package.json

 {
   "name": "antsibull-docs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript library for processing Ansible documentation markup",
@@ -5,0 +5,0 @@ "main": "dist/cjs/index.js",

README.md

@@ -108,9 +108,10 @@ <!--
 2. Create `changelogs/fragments/<version>.yml` with a `release_summary` section.
-3. Run `rm -rf dist && npm run build`.
+3. Run `rm -rf dist && npm ci && npm run build`.
 4. Run `npm publish --dry-run` and check the output.
-5. Run `antsibull-changelog release` and add the updated files to git.
-6. Commit with message `Release <version>.` and run `git tag <version>`.
-7. Run `git push upstream main && git push`.
-8. Once CI passes on GitHub, run `npm publish`.
-9. On success, do `git push upstream --tags` and create a GitHub release.
-10. Add `.post0` to the version in `package.json`, commit as `Post-release version bump.`, and push to GitHub.
+5. Add modified files to git (if they are OK) and commit with message `Prepare <version>.`.
+6. Run `antsibull-changelog release` and add the updated files to git.
+7. Commit with message `Release <version>.` and run `git tag <version>`.
+8. Run `git push upstream main && git push`.
+9. Once CI passes on GitHub, run `npm publish`.
+10. On success, do `git push upstream --tags` and create a GitHub release.
+11. Add `.post0` to the version in `package.json`, commit as `Post-release version bump.`, and push to GitHub.

src/opts.ts

@@ -127,3 +127,7 @@ /*
 
-export interface RSTOptions extends CommonExportOptions, CommonFormatOptions {}
+export interface RSTOptions extends CommonExportOptions, CommonFormatOptions {
+  /** Whether the RST should be formatted as in antsibull-docs (for use with Sphinx and the
+      sphinx_antsibull_ext extension) or with plain RST. Default: 'antsibull-docs'. */
+  style?: 'antsibull-docs' | 'plain';
+}
 
@@ -130,0 +134,0 @@ export interface AnsibleDocTextOptions extends CommonExportOptions, CommonFormatOptions {}

src/parser.ts

@@ -311,2 +311,3 @@ /*
         result.push(command.process(args, opts, source));
+        /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
       } catch (exc: any) {
@@ -313,0 +314,0 @@ error = `${exc}`;

src/rst.ts

@@ -7,3 +7,3 @@ /*
 
-import { RSTOptions, AllFormatOptions, mergeOpts, LinkProviders } from './opts';
+import { RSTOptions, AllFormatOptions, mergeOpts } from './opts';
 import { OptionNamePart, Paragraph, ReturnValuePart } from './dom';
@@ -24,3 +24,3 @@ import { addToDestination } from './format';
 
-function formatOptionLike(part: OptionNamePart | ReturnValuePart, role: string): string {
+function formatAntsibullOptionLike(part: OptionNamePart | ReturnValuePart, role: string): string {
   const result: string[] = [];
@@ -45,2 +45,29 @@ if (part.plugin) {
 
+function formatPlainOptionLike(part: OptionNamePart | ReturnValuePart): string {
+  const plugin: string[] = [];
+  if (part.plugin) {
+    plugin.push(part.plugin.type);
+    if (!['module', 'role', 'playbook'].includes(part.plugin.type)) {
+      plugin.push(' plugin');
+    }
+    plugin.push(
+      ` :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\``,
+    );
+  }
+  if (part.entrypoint !== undefined) {
+    if (plugin.length) {
+      plugin.push(', ');
+    }
+    plugin.push('entrypoint ');
+    plugin.push(quoteRST(part.entrypoint, true));
+  }
+  let value = part.name;
+  if (part.value !== undefined) {
+    value = `${value}=${part.value}`;
+  }
+  const pluginText = plugin.length ? ` (of ${plugin.join('')})` : '';
+  const mainText = `:literal:\`${quoteRST(value, true, true)}\``;
+  return `\\ ${mainText}${pluginText}\\ `;
+}
+
 const DEFAULT_FORMATTER: AllFormatOptions = {
@@ -58,11 +85,32 @@ formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
   formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
-  formatOptionName: (part) => formatOptionLike(part, 'ansopt'),
+  formatOptionName: (part) => formatAntsibullOptionLike(part, 'ansopt'),
   formatOptionValue: (part) => `\\ :ansval:\`${quoteRST(part.value, true, true)}\`\\ `,
   formatPlugin: (part) =>
     `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
-  formatReturnValue: (part) => formatOptionLike(part, 'ansretval'),
+  formatReturnValue: (part) => formatAntsibullOptionLike(part, 'ansretval'),
 };
 
+const PLAIN_FORMATTER: AllFormatOptions = {
+  formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
+  formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true)}\`\\ `,
+  formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true)}\`\\ `,
+  formatHorizontalLine: () => '\n\n------------\n\n',
+  formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true)}\`\\ `,
+  formatLink: (part) => `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `,
+  formatModule: (part) => `\\ :ref:\`${quoteRST(part.fqcn)} <ansible_collections.${part.fqcn}_module>\`\\ `,
+  formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text)} <${part.ref}>\`\\ `,
+  formatURL: (part) => `\\ ${encodeURI(part.url)}\\ `,
+  formatText: (part) => quoteRST(part.text),
+  formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
+  formatOptionName: (part) => formatPlainOptionLike(part),
+  formatOptionValue: (part) => `\\ :literal:\`${quoteRST(part.value, true, true)}\`\\ `,
+  formatPlugin: (part) =>
+    `\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
+  formatReturnValue: (part) => formatPlainOptionLike(part),
+};
+
 export function toRST(paragraphs: Paragraph[], opts?: RSTOptions): string {
-  const mergedOpts = mergeOpts(Object.assign({} as LinkProviders, opts), DEFAULT_FORMATTER);
+  opts = opts ?? {};
+  const style = opts.style || 'antsibull-docs';
+  const mergedOpts = mergeOpts(opts, style === 'antsibull-docs' ? DEFAULT_FORMATTER : PLAIN_FORMATTER);
   const result: string[] = [];
@@ -69,0 +117,0 @@ for (const paragraph of paragraphs) {

src/vectors.spec.ts

@@ -60,2 +60,9 @@ /*
     }
+    if (test_data.source !== undefined && test_data.rst_plain !== undefined) {
+      it(`${test_name} (Ansible doc => plain RST)`, (): void => {
+        expect(
+          toRST(parse(test_data.source, test_data.parse_opts), Object.assign({ style: 'plain' }, test_data.rst_opts)),
+        ).toEqual(test_data.rst_plain);
+      });
+    }
     if (test_data.source !== undefined && test_data.ansible_doc_text !== undefined) {
@@ -62,0 +69,0 @@ it(`${test_name} (Ansible doc => ansible-doc text output)`, (): void => {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

397164

increased by9.9%

Lines of code

4296

increased by3.59%

Number of lines in readme file

117

increased by0.86%

No dependency changes