a bit of documentation and reformatting

Author: gvwilson

Makefile

@@ -5,27 +5,27 @@ HANDWRITTEN=content
 SCHEMA_SRC=test/plot-schema.json
 TMP=tmp
 EXAMPLES_DIR=${TMP}/javascript
-EXAMPLES_FILE=${EXAMPLES_DIR}/axes/index.html
+EXAMPLES_FILE=${EXAMPLES_DIR}/axes/index.html # could be any of the generated files
 REFERENCE_DIR=${TMP}/reference
-REFERENCE_FILE=${REFERENCE_DIR}/bar/index.html
+REFERENCE_FILE=${REFERENCE_DIR}/bar/index.html # could be any of the generated files
 
 ## commands: show available commands
 commands:
 	@grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':'
 
-## docs: rebuild documentation
+## docs: rebuild full documentation in `./docs`
 .PHONY: docs
 docs: ${EXAMPLES_FILE} ${REFERENCE_FILE}
 	${RUN} mkdocs build
 
-## examples: build example documentation in ./tmp
+## examples: build intermediate example documentation in ./tmp
 examples: ${EXAMPLES_FILE}
 
 ${EXAMPLES_FILE}:
 	@mkdir -p ${TMP}
 	${RUN} bin/example_pages.py --indir ${HANDWRITTEN}/plotly_js --outdir ${EXAMPLES_DIR} --jsversion 3.2.1
 
-## reference: build reference documentation in ./tmp
+## reference: build intermediate reference documentation in ./tmp
 reference: ${REFERENCE_FILE}
 
 ${REFERENCE_FILE}:

bin/example_pages.py

@@ -151,12 +151,12 @@ def _make_mydiv(args, accum, path, header, content, counter):
     unique_mydiv = f"myDiv_{counter}"
     content_mydiv = content.replace("myDiv", unique_mydiv)
     content_json = escape(json.dumps(content))
-    
+
     # Get JS Version
     mkdocs_path = Path(__file__).resolve().parent.parent / "mkdocs.yml"
     config = load_config(config_file=str(mkdocs_path))
-    extra = config.get('extra', {})
-    version = extra.get('js-version')
+    extra = config.get("extra", {})
+    version = extra.get("js-version")
 
     accum.append(
         MYDIV.format(

bin/generate_reference_pages.py

@@ -4,34 +4,36 @@
 from pathlib import Path
 import mkdocs_gen_files
 
+
 def generate_pages(path, output_dir, parent, nav=None):
     """
-    Walk through the a directory and generate Markdown files that 
+    Walk through a directory and generate Markdown files that
     include the corresponding HTML snippets.
     """
     with os.scandir(path) as it:
-        entries = sorted(it, key= lambda e: e.name)
+        entries = sorted(it, key=lambda e: e.name)
         for folder in entries:
             dir_name = folder.name + ".md"
             file_path = os.path.join(output_dir, dir_name)
 
-            with open(file_path, 'w') as f:
-                f.write(f'# {folder.name}\n')
-                f.write(f'--8<-- \"{parent}/{folder.name}/index.html\"\n')
+            with open(file_path, "w") as f:
+                f.write(f"# {folder.name}\n")
+                f.write(f'--8<-- "{parent}/{folder.name}/index.html"\n')
 
             # Add markdown file to navigation
             if nav is not None:
                 nav[(folder.name)] = dir_name
 
     it.close()
 
+
 nav = mkdocs_gen_files.Nav()
 
 parent = Path(__file__).resolve().parent.parent
-ref_path = f"{parent}/tmp/reference" 
+ref_path = f"{parent}/tmp/reference"
 ref_output_dir = f"{parent}/pages/reference/"
 
-examples_path = f"{parent}/tmp/javascript" 
+examples_path = f"{parent}/tmp/javascript"
 examples_output_dir = f"{parent}/pages/examples/"
 
 os.makedirs(ref_output_dir, exist_ok=True)
@@ -40,5 +42,5 @@ def generate_pages(path, output_dir, parent, nav=None):
 generate_pages(ref_path, ref_output_dir, "reference", nav)
 generate_pages(examples_path, examples_output_dir, "javascript")
 
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:  
-    nav_file.writelines(nav.build_literate_nav())  
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())