@zero-version/document.cli

Document solutions and projects.

Usage

document will read all data files in a config directory, and use them in combination with the corresponding template files to make documentation. From a processing perspective, this allows tooling to update the data files, before running document to recreate the documentation. The data files can be configured to preserve content if there is existing documentation, before regenerating the new documentation. In the example below, the preamble and notes documentation will be preserved from the existing document, and re-inserted when the document is regenerated.

Usage: document [options]

Document solutions and projects.

Options:
  -V, --version                output the version number
  -d, --configDir <configDir>  config dir
  -h, --help                   display help for command

Examples

For example, the data file (publishReadme.json) used to generate this document looks something like this:

{
  "templateFile": "./readme.tmp",
  "outputFile": "../README.md",
  "preserve": {
    "devNotes": {
      "startTag": "<!-- DEV-NOTES -->",
      "default": "<!-- add dev notes -->",
      "endTag": "<!-- /DEV-NOTES -->"
    },
    "preamble": {
      "startTag": "<!-- PREAMBLE -->",
      "default": "<!-- add preamble -->",
      "endTag": "<!-- /PREAMBLE -->"
    },
    "usageNotes": {
      "startTag": "<!-- USAGE-NOTES -->",
      "default": "<!-- add usage notes -->",
      "endTag": "<!-- /USAGE-NOTES -->"
    }
  },
  "data": {
    "name": "@zero-version/document.cli",
    "description": "Document solutions and projects.",
    "supportHeading": "## Support ☕",
    "supportNotes": [
      "Are you using a package I've developed and finding it useful? Or have you looked at one of my repositories and learnt something new? If so, please consider [buying me a coffee](https://www.buymeacoffee.com/acrobertson). Thanks!"
    ],
    "contributingPoints": ["These [technical notes](./__docs__/TECH_NOTES.md) describe tools and scripts used by this project."]
  }
}

And the template file (publishReadme.tmp) used to generate this document looks something like this:

<%
print('<!-- PREAMBLE -->\n\n');
print(preamble + '\n\n');
print('<!-- /PREAMBLE -->\n\n');

print('<!-- NO-PUBLISH -->\n\n');
print('# ' + name + '\n\n');
print('<!-- /NO-PUBLISH -->\n\n');
print('> ' + description + '\n\n');

if(supportNotes.length > 0) {
  print(supportHeading + '\n\n');
  for (let i = 0; i < supportNotes.length; i++) {
    let supportNote = supportNotes[i];
    print(supportNote + '\n');
  }

  print('\n');
}

print('<!-- USAGE-NOTES -->\n\n');
print(usageNotes + '\n\n');
print('<!-- /USAGE-NOTES -->\n\n');

print('<!-- NO-PUBLISH -->\n\n');
print('## Contributing\n\n');

print('<!-- DEV-NOTES -->\n\n');
print(devNotes + '\n\n');
print('<!-- /DEV-NOTES -->\n\n');

for (let i = 0; i < contributingPoints.length; i++) {
  let contributionPoint = contributingPoints[i];
  print('- ' + contributionPoint + '\n');
}

print('\n');
print('<!-- /NO-PUBLISH -->');
%>

When document is run, the README.md file is initially:

<!-- PREAMBLE -->

<img src="https://github.com/script-box/assets/blob/main/common/logo.png?raw=true" width="100">

<!-- /PREAMBLE -->

<!-- NO-PUBLISH -->

# @zero-version/document.cli

<!-- /NO-PUBLISH -->

> Document solutions and projects.

## Support ☕

Are you using a package I've developed and finding it useful? Or have you looked at one of my repositories and learnt something new? If so, please consider [buying me a coffee](https://www.buymeacoffee.com/acrobertson). Thanks!

<!-- USAGE-NOTES -->

<!-- add usage notes -->

<!-- /USAGE-NOTES -->

<!-- NO-PUBLISH -->

## Contributing

<!-- DEV-NOTES -->

<!-- add dev notes -->

<!-- /DEV-NOTES -->

- These [technical notes](./__docs__/TECH_NOTES.md) describe tools and scripts used by this project.

<!-- /NO-PUBLISH -->

The preamble and notes can be changed, and they will be preserved after subsequent invocations of document.

Support ☕

Are you using a package I've developed and finding it useful? Or have you looked at one of my repositories and learnt something new? If so, please consider buying me a coffee. Thanks!