Improve documentation for DejaCode integration with SCIO, VulnerableCode and PURLDB

[mjherzog]

Our current instructions for installing DjC provides references to PURLDB and VulnerableCode in the Application Settings section, but there is no mention of the settings for SCIO integration.

The current documentation does not provide any information about which DejaCode features require integration with one or more of SCIO, VulnerableCode or PURLDB or the current options for installing these modules.

We need to document the functionality that depends on the installation and integration of other AboutCode projects and the current options for integration. We do not need to provide installation details that are better handled by the documentation for each project, but we need the big picture perspective from DejaCode.

[DennisClark]

@mjherzog There are sub-sections of the "Dataspace" section that should help:

https://dejacode.readthedocs.io/en/latest/dataspace.html#enable-package-scanning-with-your-scancode-io-server

https://dejacode.readthedocs.io/en/latest/dataspace.html#enable-purldb-service

https://dejacode.readthedocs.io/en/latest/dataspace.html#enable-vulnerablecodedb-service

Apparently these might not be obvious since they are not in the "Installation" section, and we might want to refer to those links there as well.

[mjherzog]

That is exactly my point - we need to explain the big picture upfront and not expect a new user to find it - TLDR principle I guess.

[DennisClark]

@tdruez I have attached a modified copy of installation.rst that provides a starting point for the additional guidance suggested in the previous comments in this issue. The modified filename is installation-v2024-01-15.rst . Please review and improve as needed. The changes start with a new Section 5. Thanks, and please let me know if/when you would like me to review the RTD draft.

installation-v2024-01-15.rst.zip

[tdruez]

@mjherzog @DennisClark please have a look at the following improvements:

1. New "Dataspace setup and AboutCode integrations" section in the installation chapter: https://dejacode.readthedocs.io/en/31-integration-docs/installation.html#dataspace-setup-and-aboutcode-integrations
2. Add an introduction to the "Dataspace" chapter: https://dejacode.readthedocs.io/en/31-integration-docs/dataspace.html#dataspace
3. Updated the "Enable package scanning" to setup using Dataspace configuration https://dejacode.readthedocs.io/en/31-integration-docs/dataspace.html#enable-package-scanning-with-your-scancode-io-server
4. Updated the "Enable PurlDB service" to setup using Dataspace configuration https://dejacode.readthedocs.io/en/31-integration-docs/dataspace.html#enable-purldb-service
5. Updated the "Enable VulnerableCodeDB service" to setup using Dataspace configuration https://dejacode.readthedocs.io/en/31-integration-docs/dataspace.html#enable-vulnerablecodedb-service
6. Added a new "AboutCode integrations" section in the "Application Settings" chapter https://dejacode.readthedocs.io/en/31-integration-docs/application-settings.html#aboutcode-integrations

Let me know about any required adjustments before publishing the new docs.

[DennisClark]

@tdruez Very impressive! All the improvements look good to me.

[mjherzog]

@tomd - This looks very good to me! I have two comments:

• We probably need more specific instructions regarding where we say: "Get in touch with nexB to request your credentials..." The options seem to be: 1) an Issue type in the corresponding GH repo OR 2) Contact us on nexB.com. Option 1 may be best for the near term with migrating the request to Contact Us on the new AboutCode.org website in the near future.
• For SCIO we explain that you need it to be on a separate server from DjC, but this may confuse some people because we recommend installing SCIO with Docker rather than "on a server".

[tdruez]

Documentation updates deployed at https://dejacode.readthedocs.io/

@mjherzog I've addressed your comments at:

• https://dejacode.readthedocs.io/en/latest/dataspace.html#purldb-service
• https://dejacode.readthedocs.io/en/latest/dataspace.html#vulnerablecodedb-service
• https://dejacode.readthedocs.io/en/latest/dataspace.html#install-and-configure-scancode-io

[mjherzog]

Looks good. I had forgotten also that API keys are not required for VulnerableCode and PurlDB.
Thank you.