Update documentation

Apply minor updates and fix links to installation doc

Signed-off-by: Philippe Ombredanne <[email protected]>

Author: pombredanne

README.rst

@@ -1,24 +1,23 @@
+==========
 The purldb
 ==========
-This repo consists of these main tools:
 
-- PackageDB that is the reference model (based on ScanCode toolkit)
-  that contains package data with purl (Package URLs) being a first
-  class citizen.
+This purldb consists of these main tools:
+
+- PackageDB that is the reference model (based on ScanCode toolkit) that contains package data with
+  PURL (Package URLs) being a first class citizen.
 - MineCode that contains utilities to mine package repositories
-- MatchCode that contains utilities to index package metadata and resources for
-  matching
+- MatchCode that contains utilities to index package metadata and resources for matching
 - MatchCode.io that provides package matching functionalities for codebases
 - ClearCode that contains utilities to mine Clearlydefined for package data
-- purldb-toolkit CLI utility and library to use the PurlDB, its API and various
-  related libraries.
+- purldb-toolkit CLI utility and library to use the PurlDB, its API and various related libraries.
 
-These are designed to be used first for reference such that one can query for
-packages by purl and validate purl existence.
+These are designed to be used first for reference such that one can query for packages by purl and
+validate purl existence.
 
-In the future, the collected packages will be used as reference for dependency
-resolution, as a reference knowledge base for all package data, as a reference
-for vulnerable range resolution and more.
+In the future, the collected packages will be used as reference for dependency resolution, as a
+reference knowledge base for all package data, as a reference for vulnerable range resolution and
+more.
 
 Documentation
 -------------

docs/source/how-to-guides/deploy_to_devel.rst

@@ -13,7 +13,7 @@ directly or through a command line purlcli tool sub-command.
 
 .. note::
     This tutorial assumes that you have a working installation of PurlDB and MatchCode.io
-    If you don't, please refer to the `installation <../purldb/overview.html#installation>`_ page.
+    If you don't, please refer to the `installation <../how-to-guides/installation.html#installation>`_ page.
 
 
 Why mapping binary back to sources?

docs/source/how-to-guides/installation.rst

@@ -1,12 +1,13 @@
+============
 Installation
 ============
 
-This article will detail the steps needed to set up a PurlDB instance with
-MatchCode and package scanning using Docker.
+This article details the steps needed to set up a PurlDB instance with MatchCode and package
+scanning using Docker.
 
-MatchCode.io requires that it is installed and running alongside an instance of
-PurlDB, as it needs direct access to PurlDB's data. This is done by running the
-PurlDB and MatchCode.io services on the same Docker network.
+MatchCode.io requires that it is installed and running alongside an instance of PurlDB, as it needs
+direct access to PurlDB's data. This is done by running the PurlDB and MatchCode.io services on the
+same Docker network.
 
 .. code-block:: console
 

docs/source/how-to-guides/symbols_and_strings.rst

@@ -9,7 +9,7 @@ from codebase resources.
 
 .. note::
     This tutorial assumes that you have a working installation of PurlDB.
-    If you don't, please refer to the `installation <../purldb/overview.html#installation>`_ page.
+    If you don't, please refer to the `installation <../how-to-guides/installation.html#installation>`_ page.
 
 
 Problem

docs/source/index.rst

@@ -1,24 +1,26 @@
-Welcome to PurlDB documentation!
+=========================================
+   Welcome to PurlDB documentation!
 =========================================
 
 
 PurlDB aka. ``Package URL Database`` is a database of software package metadata keyed by Package-URL
 or purl that offers information and indentication services about software packages.
 
-A purl or Package-URL is an attempt to standardize existing approaches to reliably identify and
+A PURL or Package-URL is an attempt to standardize existing approaches to reliably identify and
 locate software packages in general and Free and Open Source Software (FOSS) packages in
 particular.
 
-A purl is a URL string used to identify and locate a software package in a mostly universal and
+A PURL is a URL string used to identify and locate a software package in a mostly universal and
 uniform way across programming languages, package managers, packaging conventions, tools, APIs and
 databases.
 
 Why PurlDB?
 ------------------
 
-Modern software is assembled from 100's or 1000's of FOSS packages: being able to catalog these,
-normalize their metadata, track their versions, licenses and dependencies and being able to locate
-and identify them is essential to healthy, sustainable and secure modern software development.
+Modern software is assembled from 1000's of FOSS packages: being able to catalog these, normalize
+their metadata, track their versions, licenses and dependencies and being able to discover, locate
+and identify them as used in a codebase is essential to healthy, sustainable and secure modern
+software development.
 
 This what PurlDB is all about and it offers:
 
@@ -54,7 +56,7 @@ What's in PurlDB?
 The PurlDB project consists of these main tools:
 
 - PackageDB that is the database and reference model (based on ScanCode toolkit)
-  that contains package data with purl (Package URLs) being a first class citizen and the primaty
+  that contains package data with PURL (Package URLs) being a first class citizen and the primaty
   key to access information.
 
 - MineCode that contains utilities to mine package repositories and populate the PackageDB

docs/source/matchcode/index.rst

@@ -1,5 +1,6 @@
-Matchcode
-==========
+===========
+ Matchcode
+===========
 
 MatchCode.io
 ------------
@@ -8,12 +9,16 @@ MatchCode.io is a Django app, based off of ScanCode.io, that exposes one API
 endpoint, ``api/matching``, which takes a ScanCode.io codebase scan, and
 performs Package matching on it.
 
-Currently, it performs three matching steps:
+Currently, it performs three matching steps, using the PackageDB indices:
 
-  * Match codebase resources against the Packages in the PackageDB
-  * Match codebase resources against the Resources in the PackageDB
-  * Match codebase directories against the directory matching indices of
-    MatchCode
+* Match codebase files against whole Packages archives
+* Match exactly codebase files against files
+* Match codebase directories exactly and approximately against directory indices
+
+Upcoming features include:
+
+* Match codebase files approximately
+* Match codebase file fragments (aka. snippets) including attempting to match AI-generated code
 
 
 MatchCode.io API Endpoints
@@ -28,23 +33,23 @@ MatchCode.io API Endpoints
 Docker Setup for Local Development and Testing
 ----------------------------------------------
 
-PurlDB and MatchCode.io are two separate Django apps. In order to run both of
-these Django apps on the same host, we need to use Traefik.
+PurlDB and MatchCode.io are two separate Django apps. In order to run both of these Django apps on
+the same host, we need to use Traefik.
 
-Traefik is an edge router that receives requests and finds out which services
-are responsible for handling them. In the docker-compose.yml files for PurlDB
-and MatchCode.io, we have made these two services part of the same Docker
-network and set up the routes for each service.
+Traefik is an edge router that receives requests and finds out which services are responsible for
+handling them. In the docker-compose.yml files for PurlDB and MatchCode.io, we have made these two
+services part of the same Docker network and set up the routes for each service.
 
-All requests to the host go to the PurlDB service, but requests that go to the
-``api/matching`` endpoint are routed to the MatchCode.io service.
+All requests to the host go to the PurlDB service, but requests that go to the ``api/matching``
+endpoint are routed to the MatchCode.io service.
 
 To run PurlDB and Matchcode.io with Docker:
 ::
 
   docker compose -f docker-compose.yml up -d
   docker compose -f docker-compose.matchcodeio.yml up -d
 
+
 Scancode.io pipeline
 ---------------------
 

docs/source/matchcode/matchcode-pipeline.rst

@@ -1,13 +1,14 @@
-Code Matching
-=============
+===========================
+  Code Matching pipeline
+===========================
 
 The aim of this tutorial is to show how to use the MatchCode.io API to perform
 code matching on an archive of files.
 
 .. note::
     This tutorial assumes that you have a working installation of PurlDB. If you
     don't, please refer to the `installation
-    <../purldb/overview.html#installation>`_ page.
+    <../how-to-guides/installation.html#installation>`_ page.
 
 Throughout this tutorial, we will use ``pkg:npm/[email protected]`` and a
 modified copy of ``index.js`` from it.