antsibull-docs

antsibull-docs - TypeScript library for processing Ansible documentation markup

This is a TypeScript library for processing Ansible documentation markup. It is named after the Python package of the same name. It is the TypeScript/JavaScript version of the Python antsibull-docs-parser package, which is used by antsibull-docs.

How to use this

The package is available on npm.

Node.js (CommonJS modules)

const { parse, toHTML } = require('antsibull-docs');

function convert() {
  return toHTML(parse(['First paragraph.', 'Second B(paragraph).']));
}

Webpack (EcmaScript modules)

import { parse, toHTML } from 'antsibull-docs';

function convert(): string {
  return toHTML(parse(['First paragraph.', 'Second B(paragraph).']));
}

How to develop on this

After checking out the repository, run

$ npm install

to install all required node packages. Afterwards you can run

$ npm build

to build the package as both ESM and CJS,

$ npm build:cjs:watch
$ npm build:esm:watch

to start a watch process which builds the package (as CJS or ESM) every time a file is modified,

$ npm test

to run the unit tests,

$ npm run test:coverage

to run the unit tests and output coverage stats,

$ npm run test:watch

to start a watch process which run tests every time a file is modified,

$ npm run test:coverage:watch

to start a watch process which run tests every time a file is modified and outputs coverage stats,

$ npm run lint

to run the linting,

$ npm run format:check

to check formatting with prettier, and

$ npm run format:write

to re-format the source files.

Release

1. Update package version in package.json (and remove things like -post0).
2. Create changelogs/fragments/<version>.yml with a release_summary section.
3. Run rm -rf dist && npm install && npm run build.
4. Run npm publish --dry-run and check the output.
5. Make sure to run npm run format:write, especially if you updated this README.
6. Add modified files to git (if they are OK) and commit with message Prepare <version>..
7. Run antsibull-changelog release and add the updated files to git.
8. Commit with message Release <version>. and run git tag <version>.
9. Run git push upstream main && git push.
10. Once CI passes on GitHub, run npm publish.
11. On success, do git push upstream --tags and create a GitHub release.
12. Add -post0 to the version in package.json, run npm install, commit as Post-release version bump., and push to GitHub.