fix: add readme tests + doc dry run (#827)

Author: sesmart

docs/build_body.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 
 import json
+import os
 
 categories = {
     "new"       : "I'm new to quantum",
@@ -23,7 +24,10 @@
     "qiskit"    : "Qiskit",
 }
 
-def main():
+def main(dry_run: bool = False):
+    if not os.path.isdir("docs"):
+        raise RuntimeError("running script from the wrong directory")
+
     with open("docs/ENTRIES.json", 'r') as fp:
         # first, check that all categories are used 
         entries : dict = json.load(fp)
@@ -57,9 +61,10 @@ def main():
             main_body+= f"{text}\n\n"
 
 
-    with open("docs/_NOTEBOOKS.md",'w') as fp:
-        fp.write(main_body)
-    print("docs/_NOTEBOOK.md updated!")
+    if not dry_run:
+        with open("docs/_NOTEBOOKS.md",'w') as fp:
+            fp.write(main_body)
+        print("docs/_NOTEBOOK.md updated!")
 
 if __name__ == "__main__":
-    main()
+    main()

docs/build_index.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 
 import json
+import os
 from collections import defaultdict
 
 
@@ -61,7 +62,7 @@ def generate_index_section(terms_to_loc, loc_to_key):
         markdown = markdown[:-2] + "| <br>\n"    
     return markdown
 
-def main():
+def main(dry_run: bool = False):
     """
     build the index 
 
@@ -70,8 +71,10 @@ def main():
         - loc/locations - where the notebook is 
         - terms - keywords or index terms 
     """
-
-    with open("docs/entries.json", 'r') as fp:
+    if not os.path.isdir("docs"):
+        raise RuntimeError("running script from the wrong directory")
+    
+    with open("docs/ENTRIES.json", "r") as fp:
         entries : dict = json.load(fp)
 
     loc_to_key = {v["location"]:v["index_abbrv"] for v in entries.values()}
@@ -98,10 +101,10 @@ def main():
     index_section = generate_index_section(terms_to_loc, loc_to_key)
 
     # Update INDEX
-    with open(index_path, 'w') as f:
-        f.write(index_section)
-    
-    print("docs/_INDEX.md updated!")
+    if not dry_run:
+        with open(index_path, "w") as f:
+            f.write(index_section)
+        print("docs/_INDEX.md updated!")
 
 if __name__ == "__main__":
-    main()
+    main()

pyproject.toml

@@ -53,7 +53,8 @@ dependencies = [
 [tool.hatch.envs.default.scripts]
 test = """
 python -m ipykernel install --user --name "conda_braket" --display-name "conda_braket"
-pytest --dist worksteal -n logical -ra -v --durations=0 -m 'not mitiq' test/
+pytest -ra -v --durations=0 test/repo_tests/
+pytest --dist worksteal -n logical -ra -v --durations=0 -m 'not mitiq' test/integ_tests/
 """
 
 [tool.hatch.envs.lint]

test/integ_tests/test_all_notebooks.py

@@ -110,12 +110,18 @@ def get_mock_paths(notebook_dir, notebook_file):
 def html_exporter():
     return HTMLExporter(template_name="classic")
 
+@pytest.fixture(autouse=True)
+def restore_cwd():
+    """ after each test, move back to root_path - amazon-braket-examples/"""
+    yield
+    os.chdir(root_path)
+
+
 @pytest.mark.parametrize("notebook_dir, notebook_file", test_notebooks)
 def test_all_notebooks(notebook_dir, notebook_file, mock_level):
     if notebook_file in EXCLUDED_NOTEBOOKS:
         pytest.skip(f"Skipping Notebook: '{notebook_file}'")
 
-    os.chdir(root_path)
     os.chdir(notebook_dir)
     path_to_utils, path_to_mocks = get_mock_paths(notebook_dir, notebook_file)
     # Try to use the conda_braket kernel if installed, otherwise fall back to the default value of python3
@@ -132,7 +138,6 @@ def test_all_notebooks(notebook_dir, notebook_file, mock_level):
 
 @pytest.mark.parametrize("notebook_dir, notebook_file", test_notebooks)
 def test_notebook_to_html_conversion(notebook_dir, notebook_file, mock_level, html_exporter):
-    os.chdir(root_path)
     os.chdir(notebook_dir)
 
     html_exporter.from_file(notebook_file)
@@ -151,7 +156,6 @@ def test_record():
                 break
     if not notebook_file or not notebook_dir:
         pytest.skip(f"Notebook not found: '{notebook_file_search}'")
-    os.chdir(root_path)
     os.chdir(notebook_dir)
     path_to_utils, _path_to_mocks = get_mock_paths(notebook_dir, notebook_file)
     path_to_utils = path_to_utils.replace("mock_utils.py", "record_utils.py")

test/repo_tests/test_readme.py

@@ -1,6 +1,9 @@
+import json
 import os
 import pathlib
 import re
+import sys
+from importlib import import_module
 
 EXCLUDED_DIRS = [
     # These directories contain notebook files that should not be linked to in the README.
@@ -13,6 +16,7 @@
 
 
 def test_readme():
+    """ Each entry in the README should have an actual file in the repository """
     root_path = pathlib.Path(__file__).parent.parent.parent.resolve()
 
     examples_path = os.path.join(root_path, "examples")
@@ -40,3 +44,39 @@ def test_readme():
     assert (
         missing_in_readme == set()
     ), "There are some new notebooks that haven't been added to the README summary: "
+
+def test_readme_matches_entries():
+    """ Each entry in the README should come from an ENTRIES.json entry. """
+    root_path = pathlib.Path(__file__).parent.parent.parent.resolve()
+    
+    with open(os.path.join(root_path, "docs/ENTRIES.json"), "r") as f:
+        entries = json.load(f)
+    
+    with open(os.path.join(root_path, "README.md"), "r") as f:
+        readme = f.read()
+    
+    readme_links = set(re.findall(LINK_EXAMPLES_REGEX, readme))
+    entries_links = {entry["location"] for entry in entries.values()}
+    
+    missing_in_entries = readme_links - entries_links
+    extra_in_entries = entries_links - readme_links
+    
+    assert missing_in_entries == set(), f"README links not in ENTRIES.json: {missing_in_entries}"
+    assert extra_in_entries == set(), f"ENTRIES.json links not in README: {extra_in_entries}"
+
+def test_readme_build_successful():
+    """ Doc build should run successful as a dry_run """
+    root_path = pathlib.Path(__file__).parent.parent.parent.resolve()
+    original_cwd = os.getcwd()
+    
+    try:
+        os.chdir(root_path)
+        sys.path.insert(0, str(root_path / "docs"))
+        build_body = import_module("build_body")
+        build_index = import_module("build_index")
+        build_body.main(dry_run=True)
+        build_index.main(dry_run=True)
+    finally:
+        os.chdir(original_cwd)
+        sys.path.pop(0)
+