Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/temando/scavenger-cli

A CLI tool to aggregate files from various sources.
https://github.com/temando/scavenger-cli

Last synced: about 2 months ago
JSON representation

A CLI tool to aggregate files from various sources.

Awesome Lists containing this project

README 

        
# Scavenger CLI



[![NPM](https://img.shields.io/npm/v/scavenger-cli.svg)](https://npmjs.org/packages/scavenger-cli/)

[![Travis CI](https://img.shields.io/travis/temando/scavenger-cli.svg)](https://travis-ci.org/temando/scavenger-cli)

[![MIT License](https://img.shields.io/github/license/temando/scavenger-cli.svg)](https://en.wikipedia.org/wiki/MIT_License)



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:



```sh

$ 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](https://github.com/temando/scavenger-scent-npm/), pass the name of the scent as the first argument and any further arguments will be pass on to the scent.



```sh

$ scavenger scout npm temando:developers

```



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



```sh

$ 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:



```json

[

  {

    "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:



```sh

$ 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:



```sh

$ 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:



```sh

$ scavenger thieve remark-gitlab-artifact

```



> Note that the project name `remark-gitlab-artifact` matches `id` under the [definitions file](#definitions-file).



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



```sh

$ 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:



```json

{

  "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:



```sh

$ scavenger devour --input projects.json

```



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



```sh

$ scavenger devour --help

```