docs: implement persona-based documentation paths (fixes #250)

docs/source/aboutcode-projects/purldb-project.rst

@@ -1,4 +1,4 @@
-.. purldb-project:
+.. _purldb-project:
 
 PurlDB
 ======

docs/source/index.rst

@@ -16,6 +16,41 @@ AboutCode documentation.
 All community contributions are welcome.
 
 
+----
+
+******************
+Choose Your Path
+******************
+
+AboutCode serves different users with different goals. Choose the path that best
+describes you to find the documentation most relevant to your needs:
+
+**Legal & Compliance Professionals**
+    You're responsible for ensuring license compliance, managing open source policies,
+    or generating attribution documentation. You need high-level summaries and
+    compliance workflows.
+
+    → :ref:`persona-legal-compliance`
+
+**Security & SCA Professionals**
+    You're focused on identifying vulnerabilities, managing security risks, or
+    performing software composition analysis. You need vulnerability scanning and
+    security analysis workflows.
+
+    → :ref:`persona-security-researcher`
+
+**Developers & Integrators**
+    You're integrating AboutCode into your development workflow, CI/CD pipeline, or
+    building applications that consume AboutCode data. You need APIs, CLIs, and
+    automation guides.
+
+    → :ref:`persona-developer-integrator`
+
+.. note::
+    Not sure which path fits you? That's okay! You can explore all paths, and each
+    one includes links to the others where relevant.
+
+
 ----
 
 ********
@@ -27,6 +62,17 @@ Overview
 
    aboutcode-project-overview
 
+**************
+Persona Paths
+**************
+
+.. toctree::
+   :maxdepth: 2
+
+   personas/legal-compliance
+   personas/security-researcher
+   personas/developer-integrator
+
 ************
 Contributing
 ************

docs/source/personas/developer-integrator.rst

@@ -0,0 +1,72 @@
+.. _persona-developer-integrator:
+
+====================================
+For Developers & Integrators
+====================================
+
+If you're integrating AboutCode into your development workflow, CI/CD pipeline, or building
+applications that consume AboutCode data, this is your starting point.
+
+Quick Start Paths
+=================
+
+**Command-Line Usage**
+    → :ref:`scancode-toolkit-project` - CLI scanning and SBOM generation
+
+**API Integration**
+    → :ref:`scancodeio-project` - REST API documentation
+    → :ref:`vulnerablecode-project` - Vulnerability API
+    → https://purldb.readthedocs.io - Package metadata API
+
+**CI/CD Pipelines**
+    → :ref:`scancode-action-project` - GitHub Actions integration
+
+**SBOM Workflows**
+    → :ref:`create-sboms` - Generate SPDX and CycloneDX SBOMs
+    → :ref:`consume-sboms` - Import and process SBOMs
+
+Quick Examples
+==============
+
+**Basic CLI Scan:**
+
+.. code-block:: bash
+
+    scancode -clpieu --json-pp output.json /path/to/code
+
+**Generate SPDX SBOM:**
+
+.. code-block:: bash
+
+    scancode --spdx output.spdx /path/to/code
+
+**Python API Usage:**
+
+.. code-block:: python
+
+    import requests
+    response = requests.post(
+        'https://your-scancodeio.com/api/projects/',
+        json={'name': 'my-project'},
+        headers={'Authorization': 'Token your-api-token'}
+    )
+
+Key Concepts
+============
+
+**Package URLs (PURLs)**
+    Universal package identifiers: ``pkg:npm/express@4.18.2``
+
+**Output Formats**
+    JSON, YAML, SPDX, CycloneDX, CSV, HTML
+
+**Python Libraries**
+    - ``packageurl-python`` - Work with PURLs
+    - ``license-expression`` - Parse SPDX license expressions
+
+Also Explore
+============
+
+- :ref:`aboutcode_data` - AboutCode data structures
+- :ref:`persona-legal-compliance` - For compliance workflows
+- :ref:`persona-security-researcher` - For vulnerability analysis

docs/source/personas/legal-compliance.rst

@@ -0,0 +1,38 @@
+.. _persona-legal-compliance:
+
+========================================
+For Legal & Compliance Professionals
+========================================
+
+If you're responsible for license compliance, managing open source policies, or generating
+attribution documentation, AboutCode helps you understand what's in your software and meet
+your legal obligations.
+
+Quick Start Paths
+=================
+
+**New to AboutCode?**
+    → :ref:`start-scanning-code` - Learn the basics of scanning code
+
+**Setting Up Compliance**
+    → :ref:`manage-license-policies` - Define approved/restricted licenses
+    → :ref:`create-sboms` - Generate attribution documents
+
+**Reviewing Supplier Software**
+    → :ref:`consume-sboms` - Import and analyze vendor SBOMs
+
+**Regulatory Requirements**
+    → :ref:`cra-compliance` - EU Cyber Resilience Act support
+
+Key Tools
+=========
+
+- **DejaCode** - Enterprise compliance management platform
+- **ScanCode.io** - Web-based scanning with policy enforcement
+- **ScanCode Toolkit** - Command-line license and copyright detection
+
+Also Explore
+============
+
+- :ref:`persona-security-researcher` - If you also handle security compliance
+- :ref:`persona-developer-integrator` - For automation and CI/CD integration

docs/source/personas/security-researcher.rst

@@ -0,0 +1,43 @@
+.. _persona-security-researcher:
+
+====================================
+For Security & SCA Professionals
+====================================
+
+If you're focused on identifying vulnerabilities, managing security risks, or performing
+software composition analysis, AboutCode provides vulnerability scanning and security
+analysis capabilities.
+
+Quick Start Paths
+=================
+
+**New to Vulnerability Scanning?**
+    → :ref:`start-scanning-code` - Run your first scan
+    → https://public.vulnerablecode.io/ - Explore the vulnerability database
+
+**Analyzing Security Risks**
+    → :ref:`vulnerablecode-project` - Query CVEs and security advisories
+    → :ref:`consume-sboms` - Enrich SBOMs with vulnerability data
+
+**Integration & Automation**
+    → :ref:`persona-developer-integrator` - API and CI/CD integration
+
+Key Tools
+=========
+
+- **VulnerableCode** - Free, open vulnerability database (https://public.vulnerablecode.io/)
+- **ScanCode.io** - Scan packages and containers for vulnerabilities
+- **PurlDB** - Package metadata enrichment (https://public.purldb.io/)
+
+Understanding the Data
+======================
+
+AboutCode uses **Package URLs (PURLs)** as universal package identifiers and aggregates
+vulnerability data from NVD, GitHub Security Advisories, OSV, and ecosystem-specific
+databases. All data includes severity scores, affected version ranges, and fix information.
+
+Also Explore
+============
+
+- :ref:`persona-legal-compliance` - If you also handle license compliance
+- :ref:`persona-developer-integrator` - For CLI and API documentation