Merge pull request #811 from aboutcode-org/restructure-rtd

Update index.rst to restructure for clarity

Author: DennisClark

docs/source/index.rst

@@ -1,28 +1,12 @@
-=========================================
-   Welcome to PurlDB documentation!
-=========================================
+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>`_.
 
-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.
+Details of the Package URL specification are available `here <https://github.com/package-url>`_.
 
-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
-uniform way across programming languages, package managers, packaging conventions, tools, APIs and
-databases.
-
-Why PurlDB?
-------------------
-
-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:
+PurlDB offers: 
 
 - An active, continuously updated reference for FOSS packages origin, information and licensing,
   aka. open code knowledge base.
@@ -31,137 +15,109 @@ This what PurlDB is all about and it offers:
 - Additional utilities to help asses the quality and integrity of software packages as used in the
   software supply chain.
 
+Documentation overview
+~~~~~~~~~~~~~~~~~~~~~~
 
-What can you do 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.
+The overview below outlines how the documentation is structured
+to help you know where to look for certain things.
 
-- Access multiple services keyed by PURL, such as metadata, package versions, packages URLs, or
-  dependencies.
+.. rst-class:: clearfix row
 
+.. rst-class:: column column2 top-left
 
-What's in PurlDB?
--------------------
+Getting started
+~~~~~~~~~~~~~~~~~~~~~~
 
-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.
+Start here if you are new to PurlDB.
 
+- :doc:`getting-started/index`
 
-These are designed to be used first for reference such that one can query for
-packages by purl and validate purl existence.
+.. rst-class:: column column2 top-right
 
-Collected packages can 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 use cases. All of
-these are important to support modern software development open source assembly.
+How-To
+~~~~~~~~~~~~~~~~~~~~~~
 
+Learn via practical step-by-step guides.
 
-Getting Started
----------------
+- :doc:`how-to-guides/index`
 
-.. toctree::
-   :maxdepth: 2
+.. rst-class:: column column2 bottom-left
 
-   getting-started/index
+Reference Docs
+~~~~~~~~~~~~~~~~~~
 
-----
+Reference documentation for PurlDB features and customizations.
 
-PurlDB
-------
+- :doc:`matchcode/index`
 
-PurlDB is a database of packages, with package metadata and indexes for package
-files and archives, and various API endpoints to get data about these packages
-and match to other codebases.
+.. rst-class:: column column2 bottom-right
 
-.. toctree::
-   :maxdepth: 2
+Explanations
+~~~~~~~~~~~~~~~~~~
 
-   purldb/index
+Consult the reference to understand PurlDB concepts.
 
-----
+- :doc:`purldb/index`
 
-PurlDB toolkit
---------------
+.. rst-class:: row clearfix
 
-purldb-toolkit is command line utility and library to use the PurlDB, its API
-and various related libraries.
+Misc
+~~~~~~~~~~~~~~~
 
-.. note::
+- :doc:`license`
+- :doc:`funding`
+- :doc:`contributing`
+- :doc:`testing`
+- :doc:`changelog`
 
-    purldb-toolkit has moved to its own repo at https://github.com/aboutcode-org/purldb-toolkit
-    from its previous location at https://github.com/aboutcode-org/purldb/tree/main/purldb-toolkit
+.. include:: improve-docs.rst
 
-----
 
-Matchcode
----------
+Indices and tables
+==================
 
-Matchcode has the functionalities to index archives, files and directories for purldb
-packages and API endpoints to make matching available. A ScanCode.io pipeline for
-matching is also present to match scanned codebases.
+* :ref:`genindex`
+* :ref:`search`
 
 .. toctree::
-   :maxdepth: 2
-
-   matchcode/index
+    :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.
 
-How-To Documents
-----------------
+- Create advanced analysis for open source packages by collecting
+  :ref:`symbols_and_strings`.
 
-How-To documents explain how to accomplish specific tasks.
+- 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.
 
-.. toctree::
-   :maxdepth: 2
+- Access multiple services keyed by PURL, such as metadata, package versions, packages URLs, or
+  dependencies.
 
-   how-to-guides/index
+What's in PurlDB?
+=================
 
-----
+The PurlDB project consists of these main tools:
 
-See also
--------------
+- 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.
 
-.. toctree::
-   :maxdepth: 2
+- MineCode that contains utilities to mine package repositories and populate the PackageDB
 
-   license
-   funding
-   contributing
-   testing
-   changelog
+- 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.
 
-Indices and tables
-==================
+- ClearCode that contains utilities to mine Clearlydefined for package data.
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`