From 6d63f66cad1069f5c9b9301e9d9776492b85ae1f Mon Sep 17 00:00:00 2001
From: Kevin Ji <kyji1011@gmail.com>
Date: Thu, 23 Jun 2022 09:48:05 -0400
Subject: [PATCH] Add documentation for new ``--dir`` CLI option

Signed-off-by: Kevin Ji <kyji1011@gmail.com>
---
 docs/source/cli-reference/basic-options.rst | 55 +++++++++++++++++++++
 docs/source/rst_snippets/basic_options.rst  |  7 +++
 2 files changed, 62 insertions(+)

diff --git a/docs/source/cli-reference/basic-options.rst b/docs/source/cli-reference/basic-options.rst
index 70fbec2c1c3..fa51d944393 100644
--- a/docs/source/cli-reference/basic-options.rst
+++ b/docs/source/cli-reference/basic-options.rst
@@ -9,6 +9,61 @@
 
 ----
 
+``-dir, --additional_directories`` Options
+------------------------------------------
+
+    .. admonition:: Dependency
+
+        The option ``-dir, --additional_directories`` is a sub-option of and requires the option
+        ``--license``.
+
+    The ``-dir, --additional_directories`` option allows the user to include additional directories
+    of licenses to use in license detection.
+
+    This command only needs to be run once for each set of additional directories; in all subsequent
+    runs of Scancode with the same directories all the licenses in the directories will be cached.
+
+    The directory structure should look something like this::
+
+        licenses/
+        ├── privateLicense1/
+        │   ├── license/
+        │   │   ├── privateLicense1.LICENSE
+        │   │   └── privateLicense1.yml
+        │   └── rule/
+        │       ├── privateLicense1.RULE
+        │       └── privateLicense1.yml
+        └── privateLicense2/
+            ├── license/
+            │   ├── privateLicense2.LICENSE
+            │   └── privateLicense2.yml
+            └── rule/
+                ├── privateLicense2.RULE
+                └── privateLicense2.yml
+
+    A scan example using the ``-dir, --additional_directories PATH`` option with a single directory::
+
+        scancode -clpieu --json-pp output.json samples -dir /home/user/external_licenses/license1
+
+    You can also include multiple directories like so::
+
+        scancode -clpieu --json-pp output.json samples -dir /home/user/external_licenses/external1 -dir /home/user/external_licenses/external2
+
+    If you want to continue running scans with ``/home/user/external_licenses/external1`` and ``/home/user/external_licenses/external2``,
+    you can omit the ``-dir`` option in subsequent scans and they will still be included. ::
+
+        scancode -clpieu --json-pp output.json samples
+
+    However, if you wanted to run a scan with a new set of directories, such as ``home/user/external_licenses/external1``
+    and ``home/user/external_licenses/external3``, you would need to rerun the scan with those directories as parameters. ::
+
+        scancode -clpieu --json-pp output.json samples -dir /home/user/external_licenses/external1 -dir /home/user/external_licenses/external3
+
+
+    ..
+
+----
+
 ``--generated`` Options
 -----------------------
 
diff --git a/docs/source/rst_snippets/basic_options.rst b/docs/source/rst_snippets/basic_options.rst
index 1b7b8ae885c..e954e34d8a9 100644
--- a/docs/source/rst_snippets/basic_options.rst
+++ b/docs/source/rst_snippets/basic_options.rst
@@ -55,6 +55,13 @@ documenting a program's options. For example:
 
 .. include::  /rst_snippets/note_snippets/basic_clpieu.rst
 
+-dir, --additional_directories PATH
+
+          Include paths to directories containing additional licenses and rules to use
+          in license detection. This can be used multiple times for multiple directories.
+
+          Sub-Option of - ``--license``
+
 --generated                  Classify automatically generated code files with a flag.
 
 --max-email INT              Report only up to INT emails found in a