Scavenger CLI

Scavenger aggregates documentation from project repositories and prepares it for static HTML generation.

Installation

Install Scavenger globally for ease of use. To install Scavenger, run the following command:

$ npm install -g scavenger-cli

Using Scavenger

Scavenger provides a utility called scavenger.

scavenger provides several sub-commands commands outlined below.

scout

The scout command is responsible for discovering projects through scents. scout writes a local definitions file for use with other scavenger sub-commands. Scents are dynamically loaded packages that follow the scavenger-scent-{package-name} convention.

For example, to invoke the NPM Scent, pass the name of the scent as the first argument and any further arguments will be pass on to the scent.

$ scavenger scout npm temando:developers

For a list of options that can be uses with scout, run the following command:

$ scavenger scout --help

For maximum compatibility with scents, add these options last.

Definitions file

A definitions file is a JSON file that describes how to get the source code for project, for example:

[
  {
    "id": "remark-graphviz",
    "name": "remark-graphviz",
    "repositoryUrl": "https://github.com/temando/remark-graphviz.git",
    "commitIsh": "master"
  },
  {
    "id": "remark-gitlab-artifact",
    "name": "remark-gitlab-artifact",
    "repositoryUrl": "https://github.com/temando/remark-gitlab-artifact.git"
  }
]

fetch

The fetch command parses the definitions file from the scout command and fetches a copy of the project for the specified project id.

For example, to fetch a copy of the remark-graphviz project, run the following command:

$ scavenger fetch --input path/to/definitions.json --filter remark-graphviz

Note that remark-graphviz matches the id from the definitions file. If the --filter option is omitted, all projects defined in the definitions file will be fetched.

For a list of options that can be used with fetch, run the following command:

$ scavenger fetch --help

thieve

The thieve command takes the documentation from the fetch project and copies it into a staging area (docs sub-directory).

For example, to thieve the documentation for the remark-gitlab-artifact project, run the following command:

$ scavenger thieve remark-gitlab-artifact

Note that the project name remark-gitlab-artifact matches id under the definitions file.

For a list of options that can be uses with thieve, run the following command:

$ scavenger thieve --help

Documentation is defined as either:

• Files specified in .scavengerrc.json file located in either:
  • The project's path.
  • The current working directory of scavenger.
• The following in the project's root, if no .scavengerrc.json file is found:
  • /README.md
  • /CONTRIBUTING.md
  • /CHANGELOG.md
  • /resources/*
  • /ts-definition.json/yaml/yml

A .scavengerrc.json file completely overrides default heuristics. They are not included with thieving files. A .scavengerrc.json file in the current working directory will override one found in the project directory.

The following .scavengerrc.json explicitly includes the files that would otherwise be added by the default heuristics, the manual directory and its contents:

{
  "docs": [
    "manual",
    "README.md",
    "CONTRIBUTING.md",
    "CHANGELOG.md"
  ]
}

devour

The devour command combines the fetch and thieve commands for all projects registered in the definitions file generated by scout.

To fetch and thieve all projects listed in a definitions file called projects.json, run the following command:

$ scavenger devour --input projects.json

For a list of options that can be uses with devour, run the following command:

$ scavenger devour --help