Run

Overview

Now that the documentation is written and that configuration files are added (see previous steps), we can finally generate the documentation's HTML pages.

This can be done in two ways: using the command line interface (CLI) API, or by running it through JavaScript.

Through the CLI

The most straightforward way to run README is through the command line.

The readme.doc command (that you installed with the README package), has multiple flags and options.

There is two mandatory options:

• --input [input] (or -i [input]), with [input] being the root directory where your documentation (in Markdown) resides.

• --output [output] (or -o [output]), with [output] being the destination directory where HTML files will be generated.

  Note that the output directory can be inside the input directory. It's for example a frequent usage to set a doc input directory and a doc/generated output directory.

There are also two other heavily recommended options:

• --clean (or -c): Removes the output directory if it existed previously.

  Without this option, README will never remove files inside the output directory, which mean it could grow indefinitely if you're not careful.

• --project-version [version] (or -p [version]), with [version] being the current version of your project: Allows to indicate in your documentation pages the version they apply to.

  If your project is a JavaScript project with a package.json file, you could just rely on the version anounced in that file (e.g. by calling node -e "console.log(require('./package.json').version)") to set that property.

For example, if your root directory is doc and you want to generate your HTML documentation in doc/generated, you can run:

readme.doc --clean --input doc --output doc/generated

If you're on a JavaScript project, you can also easily rely programatically on your project's version anounced in its package.json file:

readme.doc --clean --input doc --output doc/generated --project-version $(node -e "console.log(require('./package.json').version)")

Through the JavaScript API

The JavaScript README module exposes by default a function taking three arguments:

1. The input directory
2. The output directory
3. The other options, including clean (to remove the output directory if it already existed) and version (the current version of your project)

Here's an example of how you could call it:

import readme from "@canalplus/readme.doc";

readme("./doc", "./doc/generated", {
  clean: true,
  version: "1.2.5",
});