Merge pull request #815 from aboutcode-org/refine-docs

pombredanne · web-flow · commit db3407749cff · 2026-01-24T00:46:01.000+01:00
Refine docs
diff --git a/docs/source/_static/theme_overrides.css b/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);
+    }
+}
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -1 +1,3 @@
+:orphan:
+
 .. include:: ../../CHANGELOG.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -9,16 +9,16 @@
 # 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 -----------------------------------------------------
 
 project = "PurlDB"
-copyright = "nexB Inc. and others."
+copyright = "AboutCode, nexB Inc. and others."
 author = "AboutCode.org authors and contributors"
 
 
@@ -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": "nexB",
+    "github_user": "aboutcode-org",
     "github_repo": "purldb",
     "github_version": "main",  # branch
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _contributing:
 
 Contributing to PurlDB
@@ -106,7 +108,7 @@ See also :ref:`testing` for module-specific testing commands.
 
   **You must include a "Signed-off-by" to your commit messages**::
 
-    Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>
+    Signed-off-by: Philippe Ombredanne <pombredanne@aboutcode.org>
 
 4. **Your code is now ready to be pushed as a PR**
 
diff --git a/docs/source/funding.rst b/docs/source/funding.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Funding
 =======
 
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Getting Started
 ===============
 
diff --git a/docs/source/getting-started/install.rst b/docs/source/getting-started/install.rst
@@ -21,7 +21,7 @@ Installation steps
 Once the prerequisites have been installed, set up PurlDB with the following commands:
 ::
 
-    git clone https://github.com/nexb/purldb
+    git clone https://github.com/aboutcode-org/purldb
     cd purldb
     make dev
     make envfile
diff --git a/docs/source/getting-started/introduction.rst b/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.
+
+
diff --git a/docs/source/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst
@@ -1,7 +1,7 @@
-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::
diff --git a/docs/source/improve-docs.rst b/docs/source/improve-docs.rst
@@ -0,0 +1,8 @@
+Something Missing?
+------------------
+
+If something is missing in the documentation or if you found some part confusing, please file
+an `issue <https://github.com/aboutcode-org/purldb/issues/new>`_ with your suggestions for
+improvement. Use the ``documentation`` issue label.
+
+Your help makes PurlDB and MatchCode docs better, we love hearing from you!
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -4,17 +4,20 @@ 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,
   aka. open code knowledge base.
 - A code matching capability to identify and find similar code to existing indexed FOSS code using
   this knowledge base.
-- Additional utilities to help asses the quality and integrity of software packages as used in the
+- 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
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -30,25 +33,35 @@ 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
 
@@ -57,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
 
@@ -83,41 +98,13 @@ Indices and tables
     :maxdepth: 2
     :hidden:
 
-What can you do with PurlDB?
-============================
-
-- Build a comprehensive open source software packages knowledge base. This includes the extensive
-  scan of package code 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'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
-  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.
+    getting-started/index
+    matchcode/index
+    how-to-guides/index
+    purldb/index
+    contributing
+    changelog
+    license
+    testing
 
-- ClearCode that contains utilities to mine Clearlydefined for package data.
 
diff --git a/docs/source/license.rst b/docs/source/license.rst
@@ -1,7 +1,9 @@
+:orphan:
+
 License
 =======
 
-Copyright (c) nexB Inc. and others. All rights reserved.
+Copyright (c) AboutCode, nexB Inc. and others. All rights reserved.
 
 purldb is a trademark of nexB Inc.
 
diff --git a/docs/source/matchcode/index.rst b/docs/source/matchcode/index.rst
diff --git a/docs/source/purldb/index.rst b/docs/source/purldb/index.rst
diff --git a/docs/source/purldb/rest_api.rst b/docs/source/purldb/rest_api.rst
diff --git a/docs/source/testing.rst b/docs/source/testing.rst

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`.. include:: ../../CHANGELOG.rst`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Funding`
`2`	`4`	`=======`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Getting Started`
`2`	`4`	`===============`
`3`	`5`