Explain submodules in README and bring back normalization

.github/workflows/main.yaml

@@ -67,6 +67,7 @@ jobs:
       run: |
         python tests/runtests.py ./specifications/json-ld-api/tests -l ${{ matrix.loader }}
         python tests/runtests.py ./specifications/json-ld-framing/tests -l ${{ matrix.loader }}
+        python tests/runtests.py ./specifications/normalization/tests -l ${{ matrix.loader }}
       env:
         LOADER: ${{ matrix.loader }}
   #coverage:

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "specifications/json-ld-framing"]
 	path = specifications/json-ld-framing
 	url = https://github.com/w3c/json-ld-framing.git
+[submodule "specifications/normalization"]
+	path = specifications/normalization
+	url = https://github.com/json-ld/normalization.git

CHANGELOG.md

@@ -8,6 +8,7 @@
   - Minimize async related changes to library code in this release.
   - In sync environment use `asyncio.run`.
   - In async environment use background thread.
+- The default test manifests or directories now default to the `./specifications`.
 
 ## 2.0.4 - 2024-02-16
 

README.rst

@@ -190,24 +190,54 @@ Tests
 This library includes a sample testing utility which may be used to verify
 that changes to the processor maintain the correct output.
 
-To run the sample tests you will need to get the test suite files by cloning
+To run the sample tests you will need to get the test suite files, which 
+by default, are stored in the `specifications/` folder.
+The test suites can be obtained by either using git submodules or by cloning 
+them manually.
+
+## Using git submodules
+
+The test suites are included as git submodules to ensure versions are in sync.  
+When cloning the repository, use the ``--recurse-submodules`` flag to
+automatically clone the submodules.
+If you have cloned the repository without the submodules, you can initialize 
+them with the following commands:
+
+.. code-block:: bash
+
+    git submodule init
+    git submodule update
+
+## Cloning manually
+
+You can also avoid using git submodules by manually cloning
 the ``json-ld-api``, ``json-ld-framing``, and ``normalization`` repositories
-hosted on GitHub:
+hosted on GitHub using the following commands:
+
+.. code-block:: bash
+
+    git clone https://github.com/w3c/json-ld-api ./specifications/json-ld-api
+    git clone https://github.com/w3c/json-ld-framing ./specifications/json-ld-framing
+    git clone https://github.com/json-ld/normalization ./specifications/normalization
+
+Note that you can clone these repositories into any location you wish; however,
+if you do not clone them into the default ``specifications/`` folder, you will
+need to provide the paths to the test runner as arguments when running the 
+tests, as explained below
 
-- https://github.com/w3c/json-ld-api
-- https://github.com/w3c/json-ld-framing
-- https://github.com/json-ld/normalization
+## Running the tests
 
-If the suites repositories are available as sibling directories of the PyLD
-source directory, then all the tests can be run with the following:
+If the suites repositories are available in the `specifications/` folder of the 
+PyLD source directory, then all the tests can be run with the following:
 
 .. code-block:: bash
 
     python tests/runtests.py
 
-If you want to test individual manifest ``.jsonld`` files or directories
-containing a ``manifest.jsonld``, then you can supply these files or
-directories as arguments:
+If you wish to store the test suites in a different location than the default
+``specifications/`` folder, or you want to test individual manifest ``.jsonld``
+files or directories containing a ``manifest.jsonld``, then you can supply 
+these files or directories as arguments:
 
 .. code-block:: bash
 

tests/runtests.py

@@ -94,14 +94,14 @@ def main(self):
             # tests given on command line
             test_targets = self.options.tests
         else:
-            # default to find known sibling test dirs
+            # default to find known test suite directories
             test_targets = []
-            sibling_dirs = [
-                '../json-ld-api/tests/',
-                '../json-ld-framing/tests/',
-                '../normalization/tests/',
+            spec_dirs = [
+                './specifications/json-ld-api/tests/',
+                './specifications/json-ld-framing/tests/',
+                './specifications/normalization/tests/',
             ]
-            for dir in sibling_dirs:
+            for dir in spec_dirs:
                 if os.path.exists(dir):
                     print('Test dir found', dir)
                     test_targets.append(dir)