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.

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.