docs: add instructions on using repo finder (#350)

Signed-off-by: Ben Selwyn-Smith <[email protected]>

Author: benmss

docs/source/pages/cli_usage/action_dump_defaults.rst

@@ -1,6 +1,8 @@
 .. 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/.
 
+.. _action_dump_defaults:
+
 =============
 Dump Defaults
 =============

docs/source/pages/using.rst

@@ -110,6 +110,43 @@ With the example above, the generated output reports can be seen here:
 - `micronaut-core.html <../_static/examples/micronaut-projects/micronaut-core/analyze_with_sbom/micronaut-core.html>`__
 - `micronaut-core.json <../_static/examples/micronaut-projects/micronaut-core/analyze_with_sbom/micronaut-core.json>`__
 
+'''''''''''''''''''''''''''
+Analyzing more dependencies
+'''''''''''''''''''''''''''
+
+In some cases the dependencies that Macaron discovers lack a direct connection to a repository for it to analyze. To improve results in these instances, the Repository Finding feature can be enabled. This feature makes use of a dependency's identifying information that can be found using the package registries located on the Internet.
+
+.. note:: The Repository Finding feature currently only works for Java projects via SCM meta data found within artifact POM files.
+
+This feature is enabled by default. To disable, or configure its behaviour in other ways, a custom ``defaults.ini`` should be passed to Macaron during execution.
+
+See :ref:`dump-defaults <action_dump_defaults>`, the CLI command to dump the default configurations in ``defaults.ini``. After making changes, see :ref:`analyze <analyze-action-cli>` CLI command for the option to pass the modified ``defaults.ini`` file.
+
+Within the configuration file under the ``repofinder.java`` header, five options exist: ``find_repos``, ``artifact_repositories``, ``repo_pom_paths``, ``find_parents``, ``artifact_ignore_list``. These options behave as follows:
+
+- ``find_repos`` (Values: True or False) - Enables or disables the Repository Finding feature.
+- ``artifact_repositories`` (Values: List of URLs) - Determines the remote artifact repositories to attempt to retrieve dependency information from.
+- ``repo_pom_paths`` (Values: List of POM tags) - Determines where to search for repository information in the POM files. E.g. scm.url.
+- ``find_parents`` (Values: True or False) - When enabled, the Repository Finding feature will also search for repository URLs in parents POM files of the current dependency.
+- ``artifact_ignore_list`` (Values: List of GAs) - The Repository Finding feature will skip any artifact in this list. Format is "GroupId":"ArtifactId". E.g. org.apache.maven:maven
+
+.. note:: Finding repositories requires at least one remote call, adding some additional overhead to an analysis run.
+
+An example configuration file for utilising this feature:
+
+.. code-block:: ini
+
+    [repofinder.java]
+    find_repos = True
+    artifact_repositories = https://repo.maven.apache.org/maven2
+    repo_pom_paths =
+        scm.url
+        scm.connection
+        scm.developerConnection
+    find_parents = True
+    artifact_ignore_list =
+        org.apache.maven:maven
+
 -------------------------------------
 Analyzing a locally cloned repository
 -------------------------------------