docs: update the Command Line Usage page in the Sphinx documentation (#269)

Trong Nhan Mai · web-flow · commit 2fc1b5356bca · 2023-06-02T15:19:35.000+10:00
Signed-off-by: Trong Nhan Mai &lt;trong.nhan.mai@oracle.com&gt;
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,5 +10,5 @@ Macaron documentation
    pages/installation
    pages/using
    pages/output_files
-   pages/cli_options
+   pages/cli_usage/index
    pages/apidoc/index
diff --git a/docs/source/pages/cli_options.rst b/docs/source/pages/cli_options.rst
diff --git a/docs/source/pages/cli_usage/action_analyze.rst b/docs/source/pages/cli_usage/action_analyze.rst
@@ -0,0 +1,69 @@
+.. _analyze-action-cli:
+
+=======
+Analyze
+=======
+
+-----------
+Description
+-----------
+
+Analyze a public GitHub repository (and optionally the repositories of its dependencies) to determine its SLSA posture. We currently support `SLSA v0.1 <https://slsa.dev/spec/v0.1/>`_. The support for `SLSA v1.0 <https://slsa.dev/spec/v1.0/>`_ will be added in future.
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+    usage: ./run_macaron.sh analyze
+        [-h] [-sbom SBOM_PATH] [-rp REPO_PATH] [-b BRANCH]
+        [-d DIGEST] [-pe PROVENANCE_EXPECTATION] [-c CONFIG_PATH]
+        [--skip-deps] [-g TEMPLATE_PATH]
+
+-------
+Options
+-------
+
+.. option:: -h, --help
+
+	Show this help message and exit
+
+.. option:: -sbom SBOM_PATH, --sbom-path SBOM_PATH
+
+    The path to the SBOM of the analysis target.
+
+.. option:: -rp REPO_PATH, --repo-path REPO_PATH
+
+    The path to the repository, can be local or remote
+
+
+.. option:: -b BRANCH, --branch BRANCH
+
+    The branch of the repository that we want to checkout. If not set, Macaron will use the default branch
+
+.. option:: -d DIGEST, --digest DIGEST
+
+    The digest of the commit we want to checkout in the branch. If not set, Macaron will use the latest commit
+
+.. option:: -pe PROVENANCE_EXPECTATION, --provenance-expectation PROVENANCE_EXPECTATION
+
+    The path to provenance expectation file or directory.
+
+.. option:: -c CONFIG_PATH, --config-path CONFIG_PATH
+
+    The path to the user configuration.
+
+.. option:: --skip-deps
+
+    Skip automatic dependency analysis.
+
+.. option:: -g TEMPLATE_PATH, --template-path TEMPLATE_PATH
+
+    The path to the Jinja2 html template (please make sure to use .html or .j2 extensions).
+
+-----------
+Environment
+-----------
+
+``GITHUB_TOKEN`` – The GitHub personal access token is needed for to run the analysis. For more information on how to obtain a GitHub token, see instructions in :ref:`Prepare GitHub access token <prepare-github-token>`.
diff --git a/docs/source/pages/cli_usage/action_dump_defaults.rst b/docs/source/pages/cli_usage/action_dump_defaults.rst
@@ -0,0 +1,25 @@
+=============
+Dump Defaults
+=============
+
+-----------
+Description
+-----------
+
+Dumps the ``defaults.ini`` configuration file used by Macaron to the output directory. You can make changes to this configuration file and pass it to Macaron using the ``--defaults-path`` option. See :ref:`Analyze <analyze-action-cli>` for more information.
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+    usage: ./run_macaron.sh dump-defaults [-h]
+
+-------
+Options
+-------
+
+.. option:: -h, --help
+
+	Show this help message and exit
diff --git a/docs/source/pages/cli_usage/action_verify-policy.rst b/docs/source/pages/cli_usage/action_verify-policy.rst
@@ -0,0 +1,37 @@
+=============
+Verify Policy
+=============
+
+-----------
+Description
+-----------
+
+Verify the analysis results against a Souffle Datalog policy.
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+    usage: ./run_macaron.sh verify-policy [-h] -d DATABASE (-f FILE | -s)
+
+-------
+Options
+-------
+
+.. option:: -h, --help
+
+    Show this help message and exit
+
+.. option:: -d DATABASE, --database DATABASE
+
+    Path to the database.
+
+.. option:: -f FILE, --file FILE
+
+    Path to the Datalog policy.
+
+.. option:: -s, --show-prelude
+
+    Show policy prelude.
diff --git a/docs/source/pages/cli_usage/index.rst b/docs/source/pages/cli_usage/index.rst
@@ -0,0 +1,60 @@
+.. Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved.
+.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+.. _cli-usage:
+
+==================
+Command Line Usage
+==================
+
+Use the bash script ``run_macaron.sh`` to run Macaron as a Docker container (for more information on how to get this script, please see :ref:`Download <download-macaron>`).
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+	usage: ./run_macaron.sh [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ...
+
+Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different action commands (e.g. ``analyze``), which have their own set of flags.
+
+.. note:: Running ``--help`` on the main entry ``macaron`` will only print out the help for common flags. To print the help messages for action-specific flags, please provide the name of the action you want to know about. For example: ``./run_macaron.sh analyze --help``. The documented flags for each action can be found at `Action Commands`_.
+
+--------------
+Common Options
+--------------
+
+.. option:: -h, --help
+
+	Show this help message and exit
+
+.. option:: -V, --version
+
+	Show Macaron's version number and exit
+
+.. option:: -v, --verbose
+
+	Run Macaron with more debug logs
+
+.. option:: -o OUTPUT_DIR, --output-dir OUTPUT_DIR
+
+	The output destination path for Macaron
+
+.. option:: -dp DEFAULTS_PATH, --defaults-path DEFAULTS_PATH
+
+	The path to the defaults configuration file.
+
+.. option:: -lr LOCAL_REPOS_PATH, --local-repos-path LOCAL_REPOS_PATH
+
+	The directory where Macaron looks for already cloned repositories.
+
+---------------
+Action Commands
+---------------
+
+.. toctree::
+	:glob:
+	:maxdepth: 1
+
+	action*
diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst
@@ -13,6 +13,8 @@ Prerequisites
 - Installations of ``wget`` or ``curl`` and ``bash`` must be available and on the path.
 - Docker (or docker equivalent for your host OS) must be installed, with a docker command line equivalent to Docker 17.06 (Oracle Container Runtime 19.03) and the user should be a member of the operating system group ``docker`` (to run Docker in `rootless mode <https://docs.docker.com/engine/security/rootless/>`_).
 
+.. _download-macaron:
+
 --------
 Download
 --------
@@ -41,13 +43,15 @@ To verify your setup, go to the directory containing the downloaded ``run_macaro
 
 .. note:: In the first execution, this script will download the Macaron Docker image from ``ghcr.io/oracle-samples/macaron`` which can take some time. However, the next time you run it, the docker image available on your local host will be used.
 
-.. note:: By default, ``latest`` is used as the tag for the downloaded image. You could specify the tag you want to run by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1: ``MACARON_IMAGE_TAG=0.1 && ./run_macaron.sh --help``
+.. note:: By default, ``latest`` is used as the tag for the downloaded image. You can choose a specific tag by assigning the environment variable ``MACARON_IMAGE_TAG``. For example to run Macaron v0.1.0 run: ``MACARON_IMAGE_TAG=v0.1.0 && ./run_macaron.sh --help``
+
+.. _prepare-github-token:
 
 ---------------------------
 Prepare GitHub access token
 ---------------------------
 
-A GitHub access token is **always** required when using the **analyze** command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in :ref:`Using Guide <using-guide>`.
+A GitHub access token is **always** required when using the **analyze** command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in :ref:`Using Macaron <using-macaron>`.
 
 .. code-block:: shell
 
@@ -62,4 +66,4 @@ Ideally, the GitHub token must have **read** permissions for the repositories th
 
 After generating a GitHub personal-access token, please store its value in an environment variable called ``GITHUB_TOKEN``. This environment variable will be read by Macaron for its **analyze** command.
 
-Now that you have successfully downloaded and installed Macaron, please refer to :ref:`Using Guide <using-guide>` for the instructions on how to use Macaron.
+Now that you have successfully downloaded and installed Macaron, please refer to :ref:`Using Macaron <using-macaron>` for the instructions on how to use Macaron.
diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst
@@ -1,7 +1,7 @@
 .. Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved.
 .. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
-.. _using-guide:
+.. _using-macaron:
 
 =============
 Using Macaron
@@ -98,6 +98,6 @@ We can run Macaron against the local repository at ``target`` by using this comm
 
 With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``-b``, ``-d`` or ``--skip-deps`` similar to two previous examples)
 
-The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`CLI options <cli-options>`.
+The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
 
 .. note:: If ``-lr`` is not provided, Macaron will looks inside ``<working_directory>/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.
