From 668efd682c98dd4c3af30e4587dadc077516de4e Mon Sep 17 00:00:00 2001 From: harsh Date: Mon, 28 Sep 2026 12:39:57 +0530 Subject: [PATCH] docs: add custom attribution tutorial Signed-off-by: harsh --- docs/index.rst | 2 + docs/output-files.rst | 2 + docs/tutorial_custom_attribution.rst | 107 +++++++++++++++++++++++++++ 3 files changed, 111 insertions(+) create mode 100644 docs/tutorial_custom_attribution.rst diff --git a/docs/index.rst b/docs/index.rst index 44e91c8abc..648f518ee0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,6 +44,7 @@ Learn via practical step-by-step guides. - :ref:`tutorial_cli_analyze_docker_image` - :ref:`tutorial_api_analyze_package_archive` - :ref:`tutorial_license_policies` +- :ref:`tutorial_custom_attribution` - :ref:`tutorial_vulnerablecode_integration` - :ref:`tutorial_web_ui_symbol_and_string_collection` - :ref:`tutorial_cli_end_to_end_scanning_to_dejacode` @@ -115,6 +116,7 @@ Indices and tables tutorial_cli_analyze_codebase tutorial_api_analyze_package_archive tutorial_license_policies + tutorial_custom_attribution tutorial_vulnerablecode_integration tutorial_web_ui_symbol_and_string_collection tutorial_cli_end_to_end_scanning_to_dejacode diff --git a/docs/output-files.rst b/docs/output-files.rst index e5d47d27bc..f6cea69e81 100644 --- a/docs/output-files.rst +++ b/docs/output-files.rst @@ -351,3 +351,5 @@ The following variable are available as the template context: - ``licenses`` Refer to :ref:`data_model` for the full details of available fields. + +See :ref:`tutorial_custom_attribution` for a step-by-step example. diff --git a/docs/tutorial_custom_attribution.rst b/docs/tutorial_custom_attribution.rst new file mode 100644 index 0000000000..89dbb21f68 --- /dev/null +++ b/docs/tutorial_custom_attribution.rst @@ -0,0 +1,107 @@ +.. _tutorial_custom_attribution: + +Customize the Attribution Output +================================ + +ScanCode.io generates an HTML attribution document from the packages discovered in a +project. In this tutorial, you will customize that document with a template stored in +the input codebase. + +Requirements +------------ + +You need: + +- A ScanCode.io instance and access to its Web UI. +- A codebase that can be processed by a pipeline that discovers packages. +- The ability to add files to the codebase before uploading it. + +Create the custom template +-------------------------- + +Create the template directory at the root of the codebase: + +.. code-block:: bash + + $ mkdir -p .scancode/templates + +Download the current default template as a starting point: + +.. code-block:: bash + + $ curl --location \ + https://raw.githubusercontent.com/aboutcode-org/scancode.io/main/scanpipe/templates/scanpipe/attribution.html \ + --output .scancode/templates/attribution.html + +The template uses the Django template language. Edit +``.scancode/templates/attribution.html`` to match your requirements. For example, +change the existing ``title`` element to include your company name: + +.. code-block:: html+django + + Example Corp open source attribution + +Then customize the existing ``title`` block: + +.. code-block:: html+django + + {% block title %} +

{{ project.name }} open source attribution

+

Prepared for Example Corp.

+ {% endblock %} + +The template context provides these variables: + +- ``project``: the project name, notes, and creation date. +- ``packages``: the discovered package data, including Package URLs, license + expressions, copyrights, and notice text when available. +- ``licenses``: the unique licenses referenced by the discovered packages. + +Keep the package and license loops from the default template unless you intend to +remove those sections from the output. See :ref:`data_model` for details about the +available package fields. + +Add the template to the input +----------------------------- + +The ``.scancode`` directory must be at the root of the codebase after ScanCode.io +extracts the input. Your codebase should have this structure: + +.. code-block:: text + + .scancode/ + templates/ + attribution.html + src/ + ... + +When creating an archive for upload, archive the contents of the codebase so that +``.scancode`` remains at the archive root. For example, run this command from the +codebase directory: + +.. code-block:: bash + + $ zip -r ../my-codebase.zip . + +Upload the archive to a new ScanCode.io project and run the appropriate analysis +pipeline for your input. See :ref:`built_in_pipelines` for available pipelines. + +.. note:: + You can also paste a complete template into the **Attribution template** field in + the project's **Settings** page. A template saved in that field takes precedence + over ``.scancode/templates/attribution.html``. Leave the field empty when testing + the template from the codebase. + +Generate the attribution document +--------------------------------- + +After the pipeline run completes: + +1. Open the project details page. +2. Open the **Download** menu. +3. Select **Attribution**. +4. Open the downloaded ``attribution.html`` file in a browser and verify the changes. + +If the default output is still used, verify that the template is located at +``codebase/.scancode/templates/attribution.html`` in the project workspace and that +the **Attribution template** field in the project settings is empty.