From fc8684deb6d7d61d6cdedc443ddb4d3b92398ac3 Mon Sep 17 00:00:00 2001 From: Ryan Mast Date: Mon, 13 Jan 2025 16:47:19 -0800 Subject: [PATCH] Add information to docs showing overview of how Surfactant works (#321) Add diagram showing high-level overview of Surfactant, and a lower-level diagram with more detail on how some commonly used hooks in the plugin system fit into the way that Surfactant generates SBOMs. Resolves #77 --- docs/conf.py | 40 +++++++++++++++++++++++++++++++++++++- docs/getting_started.md | 8 ++++++++ docs/images.toml | 3 +++ docs/index.md | 1 + docs/internals_overview.md | 7 +++++++ docs/requirements.txt | 3 ++- 6 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 docs/images.toml create mode 100644 docs/internals_overview.md diff --git a/docs/conf.py b/docs/conf.py index 2859b365..89430575 100644 --- a/docs/conf.py +++ b/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) diff --git a/docs/getting_started.md b/docs/getting_started.md index 508d6bb7..5f7f6815 100644 --- a/docs/getting_started.md +++ b/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 diff --git a/docs/images.toml b/docs/images.toml new file mode 100644 index 00000000..b18de22e --- /dev/null +++ b/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" diff --git a/docs/index.md b/docs/index.md index 8c9c7a48..f593d05b 100644 --- a/docs/index.md +++ b/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 ``` diff --git a/docs/internals_overview.md b/docs/internals_overview.md new file mode 100644 index 00000000..2da00510 --- /dev/null +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt index 761fc9f7..33d874bf 100644 --- a/docs/requirements.txt +++ b/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