Improve CSS

Also streamline documentation index.

Signed-off-by: Philippe Ombredanne <pombredanne@aboutcode.org>

Author: pombredanne

docs/source/_static/theme_overrides.css

@@ -24,3 +24,50 @@ div.rst-content {
         margin-left: 0px;
     }
 }
+
+.row {
+    clear: both;
+}
+
+.column img {
+    border: 1px solid gray;
+}
+
+@media only screen and (min-width: 1000px),
+only screen and (min-width: 500px) and (max-width: 768px) {
+
+    .column {
+        padding-left: 5px;
+        padding-right: 5px;
+        float: left;
+    }
+
+    .column3 {
+        width: calc(33.3% - 10px);
+    }
+
+    .column2 {
+        width: calc(50% - 11px);
+        position: relative;
+    }
+
+    .column2:before {
+        padding-top: 61.8%;
+        content: "";
+        display: block;
+        float: left;
+    }
+
+    .top-left {
+        border-right: 1px solid var(--color-background-border);
+        border-bottom: 1px solid var(--color-background-border);
+    }
+
+    .top-right {
+        border-bottom: 1px solid var(--color-background-border);
+    }
+
+    .bottom-left {
+        border-right: 1px solid var(--color-background-border);
+    }
+}

docs/source/conf.py

@@ -9,11 +9,11 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
 
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "purldb_project.settings")
+sys.path.insert(0, os.path.abspath("../../."))
 
 # -- Project information -----------------------------------------------------
 
@@ -31,28 +31,18 @@
     "sphinx.ext.intersphinx",
     "sphinx_reredirects",
     "sphinx_rtd_theme",
-    "sphinx_rtd_dark_mode",
     "sphinx.ext.extlinks",
     "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx_rtd_dark_mode",  # For the Dark Mode
 ]
 
 
-# Redirects for olds pages
-# See https://documatt.gitlab.io/sphinx-reredirects/usage.html
-redirects = {}
-
 # This points to aboutcode.readthedocs.io
 # In case of "undefined label" ERRORS check docs on intersphinx to troubleshoot
 # Link was created at commit - https://github.com/aboutcode-org/aboutcode/commit/faea9fcf3248f8f198844fe34d43833224ac4a83
 
 intersphinx_mapping = {
-    "aboutcode": ("https://aboutcode.readthedocs.io/en/latest/", None),
-    "scancode-workbench": (
-        "https://scancode-workbench.readthedocs.io/en/develop/",
-        None,
-    ),
     "scancode.io": (
         "https://scancodeio.readthedocs.io/en/latest/",
         None,
@@ -66,14 +56,13 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -85,7 +74,7 @@
 
 html_context = {
     "display_github": True,
-    "github_user": "abouctde-org",
+    "github_user": "aboutcode-org",
     "github_repo": "purldb",
     "github_version": "main",  # branch
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root

docs/source/getting-started/introduction.rst

@@ -0,0 +1,45 @@
+:orphan:
+
+Introduction
+=============
+
+What can you do with PurlDB?
+------------------------------
+
+- Build a comprehensive open source software packages knowledge base. This includes the extensive
+  scan of the code  of packages for origin, dependencies, embedded packages and licenses.
+
+- Create advanced analysis for open source packages by collecting
+  :ref:`symbols_and_strings`.
+
+- Detect software supply chain issues by mapping package binaries to their corresponding source code
+  and determining if there are possible discrepancies between sources and binaries (such as with the
+  XZ utils attack, or sources and binaries, where package may not report the exact source code
+  used to build binaries with the :ref:`deploy_to_devel` mapping analysis.
+
+- Access multiple services keyed by PURL, such as metadata, package versions, packages URLs, or
+  dependencies.
+
+
+What tools are available 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
+  key to access information.
+
+- MineCode that contains utilities to mine package repositories and populate the PackageDB
+
+- MatchCode that contains utilities to index package metadata and resources for
+  matching
+
+- MatchCode.io that provides code package and files matching functionalities for codebases
+
+- purldb-toolkit with its "purlcli" command line (CLI) utility and library to use the PurlDB, its
+  API and various related libraries.
+
+- ClearCode that contains utilities to mine Clearlydefined for package data.
+
+

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

@@ -1,9 +1,7 @@
-:orphan:
-
-How-To-Guides
+Tutorials
 =============
 
-Here are the various how-to guides for various purldb modules designed to guide you
+Here are the various how-to guides for various PurlDB modules designed to guide you
 through specific use cases:
 
 .. toctree::

docs/source/index.rst

@@ -4,8 +4,6 @@ PurlDB Documentation
 PurlDB provides tools to create and update a database of package metadata keyed by
 PURL (Package URL) and an API for the PURL data. PurlDB is an `AboutCode project <https://aboutcode.org>`_.
 
-Details of the Package URL specification are available `here <https://github.com/package-url>`_.
-
 PurlDB offers:
 
 - An active, continuously updated reference for FOSS packages origin, information and licensing,
@@ -15,6 +13,10 @@ PurlDB offers:
 - Additional utilities to help assess the quality and integrity of software packages as used in the
   software supply chain.
 
+Details of the Package URL specification are available `here <https://github.com/package-url>`_.
+
+PURL is the `official ECMA-427 standard <https://tc54.org/purl/>`_.
+
 
 Documentation overview
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -26,32 +28,40 @@ to help you know where to look for certain things.
 
 .. rst-class:: column column2 top-left
 
-
 Getting started
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Start here if you are new to PurlDB.
 
-- :doc:`getting-started/index`
+- :doc:`getting-started/introduction`
+- :doc:`getting-started/install`
+- :doc:`getting-started/install-with-scio`
+- :doc:`getting-started/tasks`
+- :doc:`getting-started/usage`
 
 .. rst-class:: column column2 top-right
 
-
-How-To
+Tutorials
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Learn via practical step-by-step guides.
 
 - :doc:`how-to-guides/index`
+- :doc:`how-to-guides/installation`
+- :doc:`how-to-guides/matchcode`
+- :doc:`how-to-guides/deploy_to_devel`
+- :doc:`how-to-guides/purl_watch_how_to`
+- :doc:`how-to-guides/symbols_and_strings`
 
 .. rst-class:: column column2 bottom-left
 
-Reference Docs
-~~~~~~~~~~~~~~~~~~
+Code Matching Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Reference documentation for PurlDB features and customizations.
+Reference documentation for MatchCode features and customizations.
 
 - :doc:`matchcode/index`
+- :doc:`matchcode/matchcode-pipeline`
 
 .. rst-class:: column column2 bottom-right
 
@@ -60,7 +70,9 @@ Explanations
 
 Consult the reference to understand PurlDB concepts.
 
-- :doc:`purldb/index`
+- :doc:`purldb/purl_watch`
+- :doc:`purldb/rest_api`
+- :doc:`purldb/symbol_and_string_collection`
 
 .. rst-class:: row clearfix
 
@@ -86,3 +98,13 @@ Indices and tables
     :maxdepth: 2
     :hidden:
 
+    getting-started/index
+    matchcode/index
+    how-to-guides/index
+    purldb/index
+    contributing
+    changelog
+    license
+    testing
+
+

docs/source/matchcode/index.rst

@@ -1,8 +1,8 @@
 :orphan:
 
-===========
- Matchcode
-===========
+===============================
+ Code Matching Reference
+===============================
 
 MatchCode.io
 ------------
@@ -11,14 +11,11 @@ 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, using the PackageDB indices:
+MatchCode performs three matching steps, using the PackageDB indices:
 
 * 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
 
@@ -48,8 +45,8 @@ 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
+    docker compose -f docker-compose.yml up -d
+    docker compose -f docker-compose.matchcodeio.yml up -d
 
 
 Scancode.io pipeline

docs/source/purldb/index.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-PURLdb
-======
+Explanations
+======================
 
 .. toctree::
    :maxdepth: 2

docs/source/purldb/rest_api.rst

@@ -1,7 +1,7 @@
 .. _rest_api:
 
-REST API
-========
+Understanding the PurlDB REST API
+====================================
 
 To get started with the REST API, visit the **PurlDB API endpoints** at
 http://localhost/api/ or http://localhost:8001/api/ if you run on a

docs/source/testing.rst

@@ -10,7 +10,7 @@ Here is how to run the tests for each PurlDB modules.
 PurlDB tests
 -------------
 
-Run all PURLdb tests
+Run all PurlDB tests
 ~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console