about
=====

**Syntax**

::

    about [OPTIONS] [COMMANDS]

**Options:**

::

    --version    Show the version and exit.
    --help       Show this message and exit.

**Commands:**

::

  attrib     LOCATION: directory, OUTPUT: output file
  check      LOCATION: directory
  gen        LOCATION: input file, OUTPUT: directory
  inventory  LOCATION: directory, OUTPUT: csv file


attrib
======

**Syntax**

::

    about attrib [OPTIONS] LOCATION OUTPUT

    LOCATION: Path to an ABOUT file or a directory containing ABOUT files.
    OUTPUT: Path to output file to write the attribution to.

**Options:**

::

    --inventory PATH            Path to an inventory file.
    --mapping                   Use for mapping between the input keys and the ABOUT field.
                                names - mapping.config
    --mapping-file              Use a custom mapping file with mapping between input
                                keys and ABOUT field names.
    --template PATH             Path to a custom attribution template.
    --vartext TEXT              Variable texts to the attribution template
    --verbose                   Show all the errors and warning.
    -q, --quiet                 Do not print any error/warning.
    -h, --help                  Show this message and exit.

Purpose
-------
Generate an attribution file which contains the all license information
from the LOCATION along with the license text.

Assume the following:

::

    '/home/about_files/'** contains all the ABOUT files [LOCATION]
    '/home/attribution/attribution.html' is the user's output path [OUTPUT]
    '/home/project/component_list.csv' is the inventory that user want to be generated

::

    $ about attrib /home/about_files/ /home/attribution/attribution.html

Options
-------

::

    --inventory

        This option allows you to define which ABOUT files should be used for attribution generation.
        For instance,
        '/home/project/component_list.csv' is the inventory that user want to be generated

    $ about attrib --inventory /home/project/component_list.csv LOCATION OUTPUT

    --mapping

        See mapping.config for details

    --mapping-file

        Same behavior as `--mapping` but with custom mapping file

    $ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT

    --template

        This option allows you to use your own template for attribution generation.
        For instance, if you have a custom template located at:
        /home/custom_template/template.html

    $ about attrib --template /home/custom_template/template.html LOCATION OUTPUT

    --vartext

        This option allow you to pass variable texts to the attribution template

    $ about attrib --vartext title="Attribution Notice" --vartext header="Product 101" LOCATION OUTPUT

        Users can use the following in the template to get the vartext:
        {{ vartext_dict['title'] }}
        {{ vartext_dict['header'] }} 

    --verbose

        This option tells the tool to show all errors found.
        The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'


The following data are passed to jinja2 and, therefore, can be used for a custom template:
 * about object: the about objects
 * common_licenses: a common license keys list in licenses.py
 * license_key_and_context: a dictionary list with license_key as a key and license text as the value
 * license_file_name_and_key: a dictionary list with license file name as a key and license key as the value
 * license_key_to_license_name: a dictionary list with license key as a key and license file name as the value


check
=====

**Syntax**

::

    about check [OPTIONS] LOCATION

    LOCATION: Path to an ABOUT file or a directory with ABOUT files.

**Options:**

::

    --verbose                Show all the errors and warning
    -h, --help               Show this message and exit.

Purpose
-------
Validating ABOUT files at LOCATION.

Options
-------

::

    --verbose

        This option tells the tool to show all errors found.
        The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'

    $ about check --verbose /home/project/about_files/


gen
===

**Syntax**

::

    about gen [OPTIONS] LOCATION OUTPUT

    LOCATION: Path to a JSON or CSV inventory file.
    OUTPUT: Path to a directory where ABOUT files are generated.

**Options:**

::

    --fetch-license KEY                 Fetch licenses text from a DejaCode API. and
                                        create <license>.LICENSE side-by-side
                                        with the generated .ABOUT file using data
                                        fetched from a DejaCode License Library. The
                                        following additional options are required:

                                        api_url - URL to the DejaCode License Library
                                        API endpoint

                                        api_key - DejaCode API key
                                        Example syntax:

                                        about gen --fetch-license 'api_url' 'api_key'
    --license-notice-text-location PATH Copy the 'license_file' from the directory to
                                        the generated location.
    --mapping                           Use for mapping between the input keys and
                                        the ABOUT field names - mapping.config
    --mapping-file                      Use a custom mapping file with mapping between input
                                        keys and ABOUT field names.
    --verbose                           Show all the errors and warning.
    -q, --quiet                         Do not print any error/warning.
    -h, --help                          Show this message and exit.

Purpose
-------
Given an inventory of ABOUT files at location, generate ABOUT files in base directory.

Options
-------

::

    --fetch-license

        Fetch licenses text from a DejaCode API. and create <license>.LICENSE side-by-side
        with the generated .ABOUT file using data fetched from a DejaCode License Library.

        This option requires 2 parameters:
            api_url - URL to the DJE License Library
            api_key - Hash key to authenticate yourself in the API.
        (Please contact nexB to get the api_* value to use for this feature)

    $ about gen --fetch-license 'api_url' 'api_key' LOCATION OUTPUT

    --license-notice-text-location

        Copy the license files and notice files to the generated location based on the 
        'license_file' and 'notice_file' value in the input from the directory

        For instance,
        the directory, /home/licenses_notices/, contains all the licenses and notices that you want:
        /home/license/apache2.LICENSE
        /home/license/jquery.js.NOTICE

    $ about gen --license-notice-text-location /home/licenses_notices/ LOCATION OUTPUT

    --mapping

        See mapping.config for details

    --mapping-file

        Same behavior as `--mapping` but with custom mapping file

    $ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT

    --verbose

        This option tells the tool to show all errors found.
        The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'


inventory
=========

**Syntax**

::

    about inventory [OPTIONS] LOCATION OUTPUT

    LOCATION: Path to an ABOUT file or a directory with ABOUT files.
    OUTPUT: Path to the JSON or CSV inventory file to create.

**Options:**

::

    --filter TEXT               Filter for the output inventory.
    -f, --format [json|csv]     Set OUTPUT file format.  [default: csv]
    --mapping                   Use file mapping.config to collect the defined not supported fields in ABOUT files.
    --mapping-file              Use a custom mapping file with mapping between input
                                keys and ABOUT field names.
    --mapping-output FILE       Use a custom mapping file with mapping between
                                ABOUT field names and output keys
    --verbose                   Show all the errors and warning.
    -q, --quiet                 Do not print any error/warning.
    -h, --help                  Show this message and exit.

Purpose
-------
Collect a JSON or CSV inventory of components from ABOUT files.

Options
-------

::

    -filter TEXT
 
        Filter for the output inventory.

    $ about inventory --filter "license_expression=gpl-2.0" LOCATION OUTPUT

    The above command will only inventory the ABOUT files which have the "license_expression: gpl-2.0"

    -f, --format [json|csv]
 
        Set OUTPUT file format.  [default: csv]

    $ about inventory -f json LOCATION OUTPUT

    --mapping

        See mapping.config for details

    --mapping-file

        Same behavior as `--mapping` but with custom mapping file

    $ about inventory --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT

    --mapping-output

        Same behavior as `--mapping-file` but with custom mapping file
        In the custom mapping file, the left side is the custom key name where
        the right side is the ABOUT field name. For instance,
        Component: name
        
        The "Component" is a custom field name for the output
        The "name" is one of the defaul ABOUT field name that user want to convert

    $ about inventory --mapping-output CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT

    --verbose

        This option tells the tool to show all errors found.
        The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'

