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

README.rst

@@ -190,22 +190,47 @@ 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
+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
+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:
 

tests/runtests.py

@@ -97,9 +97,9 @@ def main(self):
             # default to find known sibling test dirs
             test_targets = []
             sibling_dirs = [
-                '../json-ld-api/tests/',
-                '../json-ld-framing/tests/',
-                '../normalization/tests/',
+                './specifications/json-ld-api/tests/',
+                './specifications/json-ld-framing/tests/',
+                './specifications/normalization/tests/',
             ]
             for dir in sibling_dirs:
                 if os.path.exists(dir):