Add Getting Started page

.readthedocs.yaml

@@ -4,6 +4,12 @@ build:
   os: "ubuntu-20.04"
   tools:
     python: "mambaforge-latest"
+  jobs:
+    pre_build:
+      - /bin/sh "./graphviz_flowcharts/create_svg.sh"
+      - python ./graphviz_flowcharts/remove_tooltip.py
+      - python custom_checks/check_dot_ref.py
+      - python custom_checks/check_tab_ref.py 
 
 # Build from the docs/ directory with Sphinx
 sphinx:

Makefile

@@ -4,7 +4,7 @@
 SPHINXBUILD   = python -m sphinx -T -E
 BUILDDIR      = build
 SOURCEDIR     = docs
-
+GRAPH_PATH   = ./graphviz_flowcharts
 .PHONY: default clean view html
 
 default: html
@@ -18,4 +18,8 @@ clean:
 	-rm -r $(BUILDDIR)
 
 html:
+	source "${GRAPH_PATH}/create_svg.sh"
+	python $(GRAPH_PATH)/remove_tooltip.py
+	python custom_checks/check_dot_ref.py
+	python custom_checks/check_tab_ref.py 
 	$(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees -D language=en $(SOURCEDIR) $(BUILDDIR)/html

conda_dev_env.yml

@@ -5,9 +5,11 @@ dependencies:
   - python==3.11.9
   - sphinx==7.3.7 
   - myst-parser==3.0.1
+  - graphviz==12.0.0
   - pip
   - pip:
     - sphinx-book-theme==1.1.3
     - sphinx-copybutton==0.5.2
-    - sphinx-tabs==3.4.5
-    - sphinx-togglebutton==0.3.2
+    - sphinx-togglebutton==0.3.2
+    - lxml==5.3.0
+    - sphinx-design==0.6.1

custom_checks/check_dot_ref.py

@@ -0,0 +1,102 @@
+# When creating our dot files for the flowcharts, we have to use html
+# references. This is unfortunate because our normal Markdown checks 
+# will not catch these references. In this script we create a custom 
+# check that will make sure all references in a dot file and associated
+# svg file exist. 
+
+import subprocess
+import os 
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+def grep_in_directory(directory, phrase):
+    try:
+        # Use subprocess to call grep
+        result = subprocess.run(
+            ['grep', '-rl', phrase, directory],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.splitlines()
+    except subprocess.CalledProcessError as e:
+        # If grep finds no matches, it raises an error
+        if e.returncode == 1:
+            return []  # No matches found
+        else:
+            raise  # Some other error occurred
+
+def get_all_dot_files(directory):
+    file_names_without_extension = []
+
+    # List all entries in the specified directory
+    for entry in os.listdir(directory):
+        entry_path = os.path.join(directory, entry)
+        # Check if it's a file (not a directory)
+        if os.path.isfile(entry_path):
+            # Get the file name without extension
+            file_name, _ = os.path.splitext(entry)
+            file_names_without_extension.append(file_name)
+
+    return file_names_without_extension
+
+def get_xlink_hrefs(svg_file):
+    # Parse the SVG file
+    tree = ET.parse(svg_file)
+    root = tree.getroot()
+
+    # Namespace dictionary for SVG
+    namespaces = {
+        'svg': 'http://www.w3.org/2000/svg',
+        'xlink': 'http://www.w3.org/1999/xlink'
+    }
+
+    # Find all elements with 'xlink:href' attribute
+    hrefs = []
+    for elem in root.findall('.//*[@xlink:href]', namespaces):
+
+        # get hrefs and replace html with md
+        hrefs.append(elem.attrib['{http://www.w3.org/1999/xlink}href'].replace('html', 'md'))
+
+    return hrefs
+
+def check_file_exists(file_path):
+    return Path(file_path).is_file()
+
+def get_false_indices(lst):
+    return [index for index, value in enumerate(lst) if not value]
+
+if __name__ == "__main__":
+
+    # directory to search for dot file reference 
+    main_directory = "./docs"
+
+    # directory containing dot files 
+    dot_directory = "./graphviz_flowcharts/dot_files"
+
+    # get list of all dot files in the dot_directory
+    dot_file_names = get_all_dot_files(dot_directory)
+
+    for file_name in dot_file_names:
+
+        # svg reference to look for in docs
+        svg_ref = "graphviz_flowcharts/generated_images/" + file_name + ".svg"
+
+        xlink_hrefs = get_xlink_hrefs(svg_ref)
+
+        # get all files in the docs that reference an svg generated by a dot file
+        files_w_svg_ref = grep_in_directory(main_directory, svg_ref)
+
+        if files_w_svg_ref:
+
+            for file_referencing in files_w_svg_ref:
+
+                path_exists = [check_file_exists(Path(file_referencing).parent / ref) for ref in xlink_hrefs]
+
+                false_ind = get_false_indices(path_exists)
+
+                nonexistent_paths = [xlink_hrefs[ind] for ind in false_ind]
+
+                if nonexistent_paths:
+                    dot_file = 'graphviz_flowcharts/generated_images/' + file_name + '.dot'
+                    raise RuntimeError(f"The following hrefs in {dot_file} DO NOT EXIST: {nonexistent_paths}")

custom_checks/check_tab_ref.py

@@ -0,0 +1,82 @@
+# Although sphinx-design allows you to reference tabs, the format it 
+# requires is not checkable by our normal workflow. For this reason, 
+# we needed to create this script. This script finds all Markdown 
+# references that contain "?tabset-". For these references, it then 
+# ensures that all of these references are referring to existing 
+# labels provided by tabbed content. 
+
+import re
+import os 
+import pathlib
+
+
+def check_tab_reference(md_path):
+
+    # Load the Markdown file
+    with open(md_path, 'r') as file:
+        content = file.read()
+
+    # Regular expression to grab all items that are Markdown syntax for references 
+    links = re.findall(r'\[([^\]]+)\]\(([^)]+)\)', content)
+
+    # For each cross-reference identified, ensure that the tab references actually exist in the specified file
+    for link_text, link in links:
+
+        if "?tabset-" in link:
+
+            print(f"Checking the following reference from {md_path}")
+            print(f'Text: {link_text}, URL: {link} \n')
+
+            # remove html in reference name and use md instead 
+            link = link.replace('html', 'md')
+
+            # split apart reference to get individual parts
+            link_parts = re.split(r'[?=#]', link)
+
+            # assign appropriate parts so they can be checked 
+            if "tabset" not in link_parts[0]:
+                path = link_parts[0]
+                tabset_name = link_parts[1]
+                tab_name = link_parts[2]
+                tabsec_name = link_parts[3]
+            else:
+                path = None
+                tabset_name = link_parts[0]
+                tab_name = link_parts[1]
+                tabsec_name = link_parts[2]
+
+            # list of items to look for in file
+            look_for_list = [":sync-group: " + tabset_name, ":sync: " + tab_name, "(" + tabsec_name + ")="]
+
+            if path:
+
+                checked_file = os.path.join(md_file_path.parent, path)
+
+                # if there is a path in the reference, open the file
+                with open(checked_file , 'r') as file:
+                    temp_content = file.read()
+
+                # check that tabset_name, tab_name, and tabsec_name all exist in file
+                include_check = all(s in temp_content for s in look_for_list)
+            else:
+
+                checked_file = md_path
+
+                # check that tabset_name, tab_name, and tabsec_name all exist in file
+                include_check = all(s in content for s in look_for_list)
+
+            # throw an error if the tab references do not exist 
+            if not include_check:
+                raise RuntimeError(f"One of the following tab references DO NOT EXIST in {checked_file}: {look_for_list}")
+
+def find_markdown_files(dir):
+    return list(pathlib.Path(dir).rglob('*.md'))
+
+if __name__ == "__main__":
+
+    # get all markdown files in docs and check them for correct tab references 
+    current_directory = pathlib.Path.cwd()
+    markdown_files = find_markdown_files(current_directory)
+
+    for md_file_path in markdown_files:
+        check_tab_reference(md_file_path)