diff --git a/docs/index.rst b/docs/index.rst index d1ce2299c6..098aa364d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,8 @@ In this documentation, you’ll find: tutorial_vulnerablecode_integration tutorial_web_ui_symbol_and_string_collection tutorial_cli_end_to_end_scanning_to_dejacode + tutorial_custom_attribution + .. toctree:: :maxdepth: 2 diff --git a/docs/tutorial_custom_attribution.rst b/docs/tutorial_custom_attribution.rst new file mode 100644 index 0000000000..bbbb739fc8 --- /dev/null +++ b/docs/tutorial_custom_attribution.rst @@ -0,0 +1,109 @@ +Generate Attribution with a Custom Template +=========================================== + +This tutorial explains how to create and use a custom attribution template in +ScanCode.io to override the default attribution output. + +Overview +-------- + +ScanCode.io generates attribution documents based on an internal HTML template. +You can override this template at the *project level* using the web UI. + +This is useful when you want: + +- A custom layout +- Additional metadata fields +- Company branding +- Different formatting for license or copyright data + +Default Attribution Template +---------------------------- + +The built-in attribution template is stored at: + +``scanpipe/templates/scanpipe/attribution.html`` + +Use this file as a reference when creating your custom template. +Template variables follow the Jinja2 syntax, such as: + +- ``{{ resource.path }}`` +- ``{{ resource.license_expression }}`` +- ``{{ resource.copyright }}`` +- ``{{ resource.package_name }}`` + +Create Your Custom Template +--------------------------- + +Start by copying the default template and modifying it to fit your needs. + +Example simple template: + +.. code-block:: html + + + + + + Attribution + + + + +

Project Attributions

+ + {% for resource in resources %} +
+

{{ resource.package_name or resource.path }}

+

License: {{ resource.license_expression or "Unknown" }}

+

Copyright: {{ resource.copyright or "Unknown" }}

+
+ {% endfor %} + + + +Add Template to Project Settings +-------------------------------- + +1. Open your project in the ScanCode.io web UI. +2. Go to **Settings**. +3. Find the **Attribution Template** field. +4. Paste your custom HTML template directly into the field. +5. Save. + +Your template will now override the default attribution generation for that project. + +Generate and Download Attribution +--------------------------------- + +1. Open the project details page. +2. Use the **Download** dropdown. +3. Select **Attribution**. +4. The downloaded file will use your custom template. + +Troubleshooting +--------------- + +- **Missing data?** + Check variable names against the default template. + +- **HTML not rendering correctly?** + Test the HTML in a browser and simplify CSS if needed. + +- **Template not applied?** + Ensure you pasted it into the correct project settings page. + +Summary +------- + +You can generate custom attribution documents by: + +1. Reviewing the default template. +2. Creating your custom HTML file. +3. Adding it to project settings. +4. Downloading attributions using the web UI. + +This enables complete control over attribution formatting and presentation.