Update doc format

Signed-off-by: Chin Yeung Li <[email protected]>

Author: chinyeungli

docs/source/general.rst

@@ -12,19 +12,33 @@ inside your codebase, typically in preparation for a product release, side-by-si
 actual code. ABOUT file(s) have a simple, standard format that identifies components and their
 associated licenses. The current AboutCode Toolkit subcommands are:
 
--   **attrib**: Generate a Product Attribution notice document from your ABOUT file(s), JSON, CSV or XLSX. You can also generate documents for other purposes (such as a License Reference) by varying your input control file and your template.
+-   **attrib**: Generate a Product Attribution notice document from your ABOUT
+    file(s), JSON, CSV or XLSX. You can also generate documents for other
+    purposes (such as a License Reference) by varying your input control file
+    and your template.
 
--   **check**: A simple command to validate the ABOUT file(s) and output errors/warnings on the terminal.
+-   **check**: A simple command to validate the ABOUT file(s) and output
+    errors/warnings on the terminal.
 
--   **collect_redist_src**: A command to collect and copy sources that have the 'redistribute' flagged as 'True' in ABOUT file(s) or from an inventory.
+-   **collect_redist_src**: A command to collect and copy sources that have
+    the 'redistribute' flagged as 'True' in ABOUT file(s) or from an inventory.
 
--   **gen**: Create ABOUT file(s) from a Software Inventory file (.csv, .json or .xlsx format) which is typically created from a software audit, and insert these AboutCode Toolkit files into your codebase. You can regenerate the AboutCode Toolkit files from a new Software Inventory file whenever you make changes.
+-   **gen**: Create ABOUT file(s) from a Software Inventory file (.csv, .json or .xlsx format)
+    which is typically created from a software audit, and insert these AboutCode Toolkit files
+    into your codebase. You can regenerate the AboutCode Toolkit files from a new
+    Software Inventory file whenever you make changes.
 
--   **gen_license**: Fetch licenses in the license_expression field and save to the output location.
+-   **gen_license**: Fetch licenses in the license_expression field and
+    save to the output location.
 
--   **inventory**: Generate a Software Inventory list (.csv, .json or .xlsx format) from your codebase based on ABOUT file(s). Note that this Software Inventory will only include components that have AboutCode Toolkit data. In another word, if you do not create AboutCode Toolkit files for your own original software components, these components will not show up in the generated inventory.
+-   **inventory**: Generate a Software Inventory list (.csv, .json or .xlsx format)
+    from your codebase based on ABOUT file(s). Note that this Software Inventory will
+    only include components that have AboutCode Toolkit data. In another word, if you do
+    not create AboutCode Toolkit files for your own original software components,
+    these components will not show up in the generated inventory.
 
--   **transform**: A command to transform an input CSV/JSON/XLSX by applying renaming and/or filtering and then output to a new CSV/JSON/XLSX file.
+-   **transform**: A command to transform an input CSV/JSON/XLSX by applying
+    renaming and/or filtering and then output to a new CSV/JSON/XLSX file.
 
 Additional AboutCode Toolkit information is available at:
 
@@ -36,9 +50,14 @@ Key Terminology
 ===============
 Some key terminology that applies to AboutCode Toolkit tool usage:
 
--   **Software Inventory or Inventory** - means a list of all of the components in a Development codebase and the associated data about those components with a focus on software pedigree/provenance- related data for open source and third-party components.
+-   **Software Inventory or Inventory** - means a list of all of the components
+    in a Development codebase and the associated data about those components with a
+    focus on software pedigree/provenance- related data for open source and
+    third-party components.
 
--   **Product BOM or BOM** - means a subset list of the components in a Development codebase (Software Inventory) that are Deployed on a particular Product Release (a Product Bill of Materials).
+-   **Product BOM or BOM** - means a subset list of the components in a Development
+    codebase (Software Inventory) that are Deployed on a particular Product
+    Release (a Product Bill of Materials).
 
 Using gen to Generate ABOUT file(s)
 ===================================
@@ -187,7 +206,8 @@ using the same format as an .ABOUT file.
 
 The attributes that can be set in a configuration file are:
 
--   field_renamings: An optional map of source field name to target new field name that is used to rename CSV/JSON/XLSX fields.
+-   field_renamings: An optional map of source field name to target new field
+    name that is used to rename CSV/JSON/XLSX fields.
 
         ..  code-block:: none
 
@@ -201,7 +221,9 @@ field names referenced below are AFTER the renaming have been applied.
 For instance with this configuration, the field "Directory/Location" will be
 renamed to "about_resource" and "foo" to "bar":
 
--   required_fields: An optional list of required field names that must have a value, beyond the standard field names. If a source CSV/JSON/XLSX does not have such a field or an entry is missing a value for a required field, an error is reported.
+-   required_fields: An optional list of required field names that must have a value,
+    beyond the standard field names. If a source CSV/JSON/XLSX does not have such a field or
+    an entry is missing a value for a required field, an error is reported.
 
 For instance with this configuration, an error will be reported if the fields "name"
 and "version" are missing, or if any entry does not have a value set for these fields:
@@ -212,17 +234,24 @@ and "version" are missing, or if any entry does not have a value set for these f
                 - name
                 - version
 
--   field_filters: An optional list of fields that should be kept in the transformed file. If this list is provided, only the fields that are in the list will be kept. All others will be filtered out even if they are AboutCode Toolkit standard fields. If this list is not provided, all source fields are kept in the transformed target file.
+-   field_filters: An optional list of fields that should be kept in the transformed file.
+    If this list is provided, only the fields that are in the list will be kept. All others will
+    be filtered out even if they are AboutCode Toolkit standard fields. If this list is not
+    provided, all source fields are kept in the transformed target file.
 
-For instance with this configuration, the target file will only contains the "name" and "version" fields:
+For instance with this configuration, the target file will only contains the "name" and
+"version" fields:
 
         ..  code-block:: none
 
             field_filters:
                 - name
                 - version
 
--   exclude_fields: An optional list of field names that should be excluded in the transformed file. If this list is provided, all the fields from the source file that should be excluded in the target file must be listed. Excluding required fields will cause an error. If this list is not provided, all source fields are kept in the transformed target file.
+-   exclude_fields: An optional list of field names that should be excluded in the transformed
+    file. If this list is provided, all the fields from the source file that should be
+    excluded in the target file must be listed. Excluding required fields will cause an error.
+    If this list is not provided, all source fields are kept in the transformed target file.
 
 For instance with this configuration, the target file will not contain the "type" and "temp" fields:
 
@@ -249,7 +278,9 @@ This gen example command does the following:
 
 -   Activates the --fetch-license option to get license information from ScanCode LicenseDB.
 
--   Activates the --reference option to get license text files and notice text files that you have specified in your software inventory to be copied next to the associated .ABOUT files when those are created.
+-   Activates the --reference option to get license text files and notice text files that
+    you have specified in your software inventory to be copied next to the
+    associated .ABOUT files when those are created.
 
 -   Specifies the path of the software inventory to control the processing.
 
@@ -431,7 +462,8 @@ Note that this example attrib command does the following:
 
 -   Specifies the full path (include file name) of the output document to be generated.
 
-A successful execution of attrib will create a .html (or .json depends on the template) file that is ready to use to meet your attribution requirements.
+A successful execution of attrib will create a .html (or .json depends on the template)
+file that is ready to use to meet your attribution requirements.
 
 Using inventory to Generate a Software Inventory
 ================================================

docs/source/reference.rst

@@ -157,7 +157,8 @@ Details
 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
- * licenses_list: a license object list contains all the licenses found in about objects. It contains the following attribute: key, name, filename, url, text
+ * licenses_list: a license object list contains all the licenses found in about objects.
+   It contains the following attribute: key, name, filename, url, text
 
 check
 =====

docs/source/specification.rst

@@ -44,11 +44,13 @@ A simple and valid ABOUT file named httpd-2.4.3.tar.gz.ABOUT may look like this:
 
 The meaning of this ABOUT file is:
 
--   The file "httpd-2.4.3.tar.gz" is stored in the same directory and side-by-side with the ABOUT file "httpd-2.4.3.tar.gz.ABOUT" that documents it.
+-   The file "httpd-2.4.3.tar.gz" is stored in the same directory and side-by-side with
+    the ABOUT file "httpd-2.4.3.tar.gz.ABOUT" that documents it.
 -   The name of this component is "Apache HTTP Server" with version "2.4.3".
 -   The home URL for this component is http://httpd.apache.org
 -   The file "httpd-2.4.3.tar.gz" was originally downloaded from http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz
--   In the same directory, "apache-2.0.LICENSE" and "httpd.NOTICE" are files that contain respectively the license text and the notice text for this component.
+-   In the same directory, "apache-2.0.LICENSE" and "httpd.NOTICE" are files
+    that contain respectively the license text and the notice text for this component.
 -   This component is licensed under "apache-2.0"
 -   The license for this component is defined in the SPDX License List at https://spdx.org/licenses/Apache-2.0.html
 
@@ -70,7 +72,11 @@ A file name can contain only these US-ASCII characters:
 -   digits from 0 to 9
 -   uppercase and lowercase letters from A to Z
 -   the following symbols: ``"_", "-", "+", ".", "(", ")", "~", "[", "]", "{", "}", "@", "%"``
--   The case of a file name is not significant. On case-sensitive file systems (such as on Linux), a tool must report an error if two ABOUT files stored in the same directory have the same lowercase file name. This is to ensure that ABOUT files can be used across file systems. The convention is to use a lowercase file name and an uppercase ABOUT extension.
+-   The case of a file name is not significant. On case-sensitive file systems
+    (such as on Linux), a tool must report an error if two ABOUT files stored in the same
+    directory have the same lowercase file name. This is to ensure that ABOUT files can be
+    used across file systems. The convention is to use a lowercase file name and an uppercase
+    ABOUT extension.
 
 Lines of text
 -------------
@@ -90,8 +96,11 @@ A field name can contain only these US-ASCII characters:
 -   digits from 0 to 9
 -   uppercase and lowercase letters from A to Z
 -   the ``"_"`` underscore sign.
--   Field names are not case sensitive. For example, "HOMEPAGE_URL" and "HomePage_url" represent the same field name.
--   A field name must start at the beginning of a new line. No spaces is allowed in the field name. It can be followed by one or more spaces that must be ignored. These spaces are commonly used to improve the readability of an ABOUT file.
+-   Field names are not case sensitive. For example, "HOMEPAGE_URL" and "HomePage_url"
+    represent the same field name.
+-   A field name must start at the beginning of a new line. No spaces is allowed in
+    the field name. It can be followed by one or more spaces that must be ignored.
+    These spaces are commonly used to improve the readability of an ABOUT file.
 
 Field value
 -----------
@@ -254,10 +263,16 @@ mandatory field are missing.
 Optional Information fields
 ---------------------------
 
--   version: Component or package version. A component or package usually has a version, such as a revision number or hash from a version control system (for a snapshot checked out from VCS such as Subversion or Git). If not available, the version should be the date the component was provisioned, in an ISO date format such as 'YYYY-MM-DD'.
--   spec_version: The version of the ABOUT file format specification used for this file. This is provided as a hint to readers and tools in order to support future versions of this specification.
+-   version: Component or package version. A component or package usually has a version,
+    such as a revision number or hash from a version control system (for a snapshot checked
+    out from VCS such as Subversion or Git). If not available, the version should be the date
+    the component was provisioned, in an ISO date format such as 'YYYY-MM-DD'.
+-   spec_version: The version of the ABOUT file format specification used for this file.
+    This is provided as a hint to readers and tools in order to support future versions
+    of this specification.
 -   description: Component description, as a short text.
--   download_url: A direct URL to download the original file or archive documented by this ABOUT file.
+-   download_url: A direct URL to download the original file or archive documented
+    by this ABOUT file.
 -   homepage_url: URL to the homepage for this component.
 -   changelog_file: Changelog file for the component.
 -   package_url: Package URL for the package.
@@ -266,9 +281,11 @@ Optional Information fields
 Optional Owner and Author fields
 --------------------------------
 
--   owner: The name of the primary organization or person(s) that owns or provides the component.
+-   owner: The name of the primary organization or person(s) that owns or
+    provides the component.
 -   owner_url: URL to the homepage for the owner.
--   contact: Contact information (such as an email address or physical address) for the component owner.
+-   contact: Contact information (such as an email address or physical address)
+    for the component owner.
 -   author: Name of the organization(s) or person(s) that authored the component.
 -   author_file: Author file for the component.
 
@@ -278,21 +295,33 @@ Optional Licensing fields
 -   copyright: Copyright statement for the component.
 -   notice_file: Legal notice or credits for the component.
 -   notice_url: URL to a legal notice for the component.
--   license_file: License file that applies to the component. For example, the name of a license file such as LICENSE or COPYING file extracted from a downloaded archive.
+-   license_file: License file that applies to the component. For example, the
+    name of a license file such as LICENSE or COPYING file extracted from a
+    downloaded archive.
 -   license_url: URL to the license text for the component.
--   license_expression: The DejaCode license expression that apply to the component. You can separate each identifier using " or " and " and " to document the relationship between multiple license identifiers, such as a choice among multiple licenses (No special characters are allowed).
--   license_name: The DejaCode license short name for the license (No special characters are allowed).
--   license_key: The DejaCode license key(s) for the component (No special characters are allowed).
--   spdx_license_key: The ScanCode LicenseDB spdx_license_key defined for the license at https://scancode-licensedb.aboutcode.org/index.html
+-   license_expression: The DejaCode license expression that apply to
+    the component. You can separate each identifier using " or " and " and " to
+    document the relationship between multiple license identifiers, such as a choice
+    among multiple licenses (No special characters are allowed).
+-   license_name: The DejaCode license short name for the license
+    (No special characters are allowed).
+-   license_key: The DejaCode license key(s) for the component
+    (No special characters are allowed).
+-   spdx_license_key: The ScanCode LicenseDB spdx_license_key defined
+    for the license at https://scancode-licensedb.aboutcode.org/index.html
 
 Optional Boolean flag fields
 ----------------------------
 
--   redistribute: Set this flag to yes if the component license requires source code redistribution. Defaults to no when absent.
--   attribute: Set this flag to yes if the component license requires publishing an attribution or credit notice. Defaults to no when absent.
--   track_changes: Set this flag to yes if the component license requires tracking changes made to a the component. Defaults to no when absent.
+-   redistribute: Set this flag to yes if the component license requires source code
+    redistribution. Defaults to no when absent.
+-   attribute: Set this flag to yes if the component license requires publishing an attribution
+    or credit notice. Defaults to no when absent.
+-   track_changes: Set this flag to yes if the component license requires tracking changes made to
+    a the component. Defaults to no when absent.
 -   modified: Set this flag to yes if the component has been modified. Defaults to no when absent.
--   internal_use_only: Set this flag to yes if the component is used internal only. Defaults to no when absent.
+-   internal_use_only: Set this flag to yes if the component is used internal only.
+    Defaults to no when absent.
 
 Optional Extension fields
 -------------------------
@@ -312,8 +341,10 @@ prefix and a few common fields to handle the diversity of ways that VCS
 tools reference files and directories under version control:
 
 -   vcs_tool: VCS tool such as git, svn, cvs, etc.
--   vcs_repository: Typically a URL or some other identifier used by a VCS tool to point to a repository such as an SVN or Git repository URL.
--   vcs_path: Path used by a particular VCS tool to point to a file, directory or module inside a repository.
+-   vcs_repository: Typically a URL or some other identifier used by a
+    VCS tool to point to a repository such as an SVN or Git repository URL.
+-   vcs_path: Path used by a particular VCS tool to point to a file,
+    directory or module inside a repository.
 -   vcs_tag: tag name or path used by a particular VCS tool.
 -   vcs_branch: branch name or path used by a particular VCS tool.
 -   vcs_revision: revision identifier such as a revision hash or version number.
@@ -344,7 +375,8 @@ to verify the integrity of a file documented by an ABOUT file.
 
 -   checksum_md5: MD5 for the file documented by this ABOUT file in the "about_resource" field.
 -   checksum_sha1: SHA1 for the file documented by this ABOUT file in the "about_resource" field.
--   checksum_sha256: SHA256 for the file documented by this ABOUT file in the "about_resource" field.
+-   checksum_sha256: SHA256 for the file documented by this ABOUT file in
+    the "about_resource" field.
 
 Some examples: