Add information to docs showing overview of how Surfactant works

docs/conf.py

@@ -1,3 +1,13 @@
+import os
+import sys
+
+import requests
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -24,7 +34,7 @@
 ]
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "images.toml"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -49,3 +59,31 @@
 html_favicon = html_logo
 html_sidebars = {"**": ["globaltoc.html", "relations.html", "searchbox.html"]}
 html_static_path = ["_static"]
+
+
+# -- Fetch image references --------------------------------------------------
+# Download all of the image files referenced in images.toml
+def download_images_from_toml(toml_file, image_dir):
+    with open(toml_file, "rb") as f:
+        data = tomllib.load(f)
+
+    if not os.path.exists(image_dir):
+        os.makedirs(image_dir)
+
+    for file_name, url in data.get("images", {}).items():
+        if file_name and url:
+            response = requests.get(url)
+            if response.status_code == 200:
+                with open(os.path.join(image_dir, file_name), "wb") as img_file:
+                    img_file.write(response.content)
+            else:
+                print(f"Failed to download {url}")
+
+
+# Path to the TOML file
+toml_file_path = os.path.join(os.path.dirname(__file__), "images.toml")
+# Directory to save the images
+image_directory = os.path.join(os.path.dirname(__file__), "img")
+
+# Download images
+download_images_from_toml(toml_file_path, image_directory)

docs/getting_started.md

@@ -75,6 +75,14 @@ pip install -e ".[test,dev]"
 
 `pip install` with the `-e` or `--editable` option can also be used to install Surfactant plugins for development.
 
+## Generating an SBOM
+
+To create an SBOM, run the `surfactant generate` subcommand. For more details on the options it takes, please refer to this page on [basic usage](basic_usage.md). For more information on writing Surfactant configuration files for software specimens, see the [configuration files](configuration_files.md) page.
+
+The following diagram gives a high-level overview of what Surfactant does. The [internal implementation overview](internals_overview.md) page gives more detail about how Surfactant works internally.
+
+![Surfactant Overview Diagram](img/surfactant_overview_diagram.svg)
+
 ## Understanding the SBOM Output
 
 The following is a brief overview of the default SBOM file output format (which follows the CyTRICS schema). It is

docs/images.toml

@@ -0,0 +1,3 @@
+[images]
+"surfactant_overview_diagram.svg" = "https://user-images.githubusercontent.com/3969255/281565514-114069a2-1bdc-49c7-9e5b-9ffa5ee0d0ca.svg"
+"surfactant_internal_sbom_generate_diagram.svg" = "https://user-images.githubusercontent.com/3969255/281575236-afea8787-db34-4d07-aea4-6c6eea9a6a93.svg"

docs/index.md

@@ -31,6 +31,7 @@ Some links to pages that may be useful are:
    settings
    contribution_guide
    changelog
+   internals_overview.md
    api_reference
 ```
 

docs/internals_overview.md

@@ -0,0 +1,7 @@
+# Internal Implementation
+
+Surfactant is built around a plugin architecture, allowing other developers to extend its functionality. Most of the functionality Surfactant has for generating an SBOM is also implemented using the same set of hooks that are available for others. The [plugins](plugins.md) page has more information on how to write a plugin for Surfactant.
+
+The following diagram gives a rough overview of how Surfactant works internally, and shows when some of the main types of plugin hooks get called when generating an SBOM.
+
+![Surfactant Internal Design](img/surfactant_internal_sbom_generate_diagram.svg)

docs/requirements.txt

@@ -1,9 +1,10 @@
 sphinx
 myst-parser
+tomli >= 1.1.0 ; python_version < "3.11"
+requests==2.32.3
 #sphinx_rtd_theme==1.0.0
 #ipython==7.31.1
 #ipykernel==6.4.2
 #breathe==4.31.0
 #sphinxcontrib-svg2pdfconverter==1.1.1
-#requests==2.31.0
 #sphinxcontrib-mermaid==0.8.1