Merge pull request #450 from nexB/249-update-purldb-docs

Update purldb-toolkit and related README files #249

Author: AyanSinhaMahapatra

README.rst

@@ -1,6 +1,6 @@
 The purldb
 ==========
-This repo consists of four main tools:
+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
@@ -10,6 +10,8 @@ This repo consists of four main tools:
   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.
 
 These are designed to be used first for reference such that one can query for
 packages by purl and validate purl existence.
@@ -191,37 +193,3 @@ 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
-
-Funding
--------
-
-This project was funded through the NGI Assure Fund https://nlnet.nl/assure, a
-fund established by NLnet https://nlnet.nl/ with financial support from the
-European Commission's Next Generation Internet programme, under the aegis of DG
-Communications Networks, Content and Technology under grant agreement No 957073.
-
-This project is also funded through grants from the Google Summer of Code
-program, continuing support and sponsoring from nexB Inc. and generous
-donations from multiple sponsors.
-
-
-License
--------
-
-Copyright (c) nexB Inc. and others. All rights reserved.
-
-purldb is a trademark of nexB Inc.
-
-SPDX-License-Identifier: Apache-2.0 AND CC-BY-SA-4.0
-
-purldb software is licensed under the Apache License version 2.0.
-
-purldb data is licensed collectively under CC-BY-SA-4.0.
-
-See https://www.apache.org/licenses/LICENSE-2.0 for the license text.
-
-See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license text.
-
-See https://github.com/nexB/purldb for support or download.
-
-See https://aboutcode.org for more information about nexB OSS projects.

docs/scripts/sphinx_build_link_check.sh

@@ -1,5 +1,5 @@
-Contirbute
-===========
+Contribute
+==========
 
 Documentation to support code and documentation contributions
 to purldb.

docs/source/getting-started/contribute.rst

@@ -2,10 +2,7 @@ How-To-Guides
 =============
 
 Here are the various how-to guides across various purldb projects to guide you
-thourgh specifica use cases:
-
-- Code matching with Matchcode
-- Getting symbols from a package (or a PURL)
+through specific use cases:
 
 .. toctree::
    :maxdepth: 2

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

@@ -65,6 +65,16 @@ How-To documents explain how to accomplish specific tasks.
 
 ----
 
+Miscellaneous
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   miscellaneous/index
+
+----
+
 
 Indices and tables
 ==================

docs/source/index.rst

@@ -0,0 +1,11 @@
+Funding
+=======
+
+This project was funded through the NGI Assure Fund https://nlnet.nl/assure, a
+fund established by NLnet https://nlnet.nl/ with financial support from the
+European Commission's Next Generation Internet programme, under the aegis of DG
+Communications Networks, Content and Technology under grant agreement No 957073.
+
+This project is also funded through grants from the Google Summer of Code
+program, continuing support and sponsoring from nexB Inc. and generous
+donations from multiple sponsors.

docs/source/miscellaneous/funding.rst

@@ -0,0 +1,9 @@
+Miscellaneous
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   testing
+   funding
+   license

docs/source/miscellaneous/index.rst

@@ -0,0 +1,20 @@
+License
+=======
+
+Copyright (c) nexB Inc. and others. All rights reserved.
+
+purldb is a trademark of nexB Inc.
+
+SPDX-License-Identifier: Apache-2.0 AND CC-BY-SA-4.0
+
+purldb software is licensed under the Apache License version 2.0.
+
+purldb data is licensed collectively under CC-BY-SA-4.0.
+
+See https://www.apache.org/licenses/LICENSE-2.0 for the license text.
+
+See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license text.
+
+See https://github.com/nexB/purldb for support or download.
+
+See https://aboutcode.org for more information about nexB OSS projects.

docs/source/miscellaneous/license.rst

@@ -0,0 +1,31 @@
+Testing
+=======
+
+PURLdb
+------
+
+Run all PURLdb tests
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+    make test
+
+
+purldb-toolkit
+--------------
+
+Run all purldb-toolkit non-live tests (i.e., no live network calls)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+    DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli.py
+
+
+Run all purldb-toolkit live tests (i.e., check actual API endpoints etc.)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+    DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli_live.py --run_live_fetch