Merge pull request #7 from daexs/clean-up-mkdocs-build

refactor: move documentation generation into the root directory

Author: gvwilson

.gitignore

@@ -19,3 +19,5 @@ tags
 !.circleci
 !.gitignore
 !.npmignore
+
+tmp

Makefile

@@ -0,0 +1,51 @@
+# Manage plotly.js documentation.
+
+RUN = uv run
+DOC_SRC=docs/_posts
+SCHEMA_SRC=test/plot-schema.json
+
+## commands: show available commands
+commands:
+	@grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':'
+
+## doc: rebuild documentation
+.PHONY: doc
+doc:
+	make examples
+	make reference
+	make build
+
+## examples: build example documentation in ./tmp
+examples:
+	@mkdir -p tmp
+	${RUN} bin/example_pages.py --indir ${DOC_SRC}/plotly_js --outdir tmp/javascript --jsversion 3.2.1
+
+## format: reformat Python code
+format:
+	@ruff format bin
+
+## lint: check code and project
+lint:
+	@ruff check bin
+
+## reference: build reference documentation in ./tmp
+reference:
+	@mkdir -p tmp
+	${RUN} bin/reference_pages.py --schema ${SCHEMA_SRC} --outdir tmp/reference ${DOC_SRC}/reference_pages/javascript/*.html
+
+## serve: display documentation
+serve:
+	${RUN} mkdocs serve
+
+## website: build documentation with mkdocs using already-built examples and reference
+website:
+	${RUN} mkdocs build
+
+## --: --
+
+## clean: clean up repository
+clean:
+	@find . -name '*~' -delete
+	@find . -name '.DS_Store' -delete
+	@rm -rf _site
+	@rm -f ${SCHEMA_DST}

docs/bin/example_pages.py renamed to bin/example_pages.py

@@ -153,7 +153,7 @@ def _make_mydiv(args, accum, path, header, content, counter):
     content_json = escape(json.dumps(content))
 
     # Get JS Version
-    mkdocs_path = Path(__file__).resolve().parents[2] / "mkdocs.yml"
+    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')

bin/generate_reference_pages.py

@@ -1,11 +1,13 @@
+"""Generate reference pages to satisfy MkDocs."""
+
 import os
 from pathlib import Path
 import mkdocs_gen_files
 
 def generate_pages(path, output_dir, parent, nav=None):
     """
-    Walks through the path and generates markdown files that 
-    include the corresponding html snippets in it.
+    Walk through the 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)
@@ -25,19 +27,18 @@ def generate_pages(path, output_dir, parent, nav=None):
 
 nav = mkdocs_gen_files.Nav()
 
-parent = Path(__file__).resolve().parents[1]
-ref_path = f"{parent}/docs/tmp/reference" 
+parent = Path(__file__).resolve().parent.parent
+ref_path = f"{parent}/tmp/reference" 
 ref_output_dir = f"{parent}/pages/reference/"
 
-examples_path = f"{parent}/docs/tmp/javascript" 
+examples_path = f"{parent}/tmp/javascript" 
 examples_output_dir = f"{parent}/pages/examples/"
 
-# Make directories if it doesn't exist
 os.makedirs(ref_output_dir, exist_ok=True)
 os.makedirs(examples_output_dir, exist_ok=True)
 
 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())  
+    nav_file.writelines(nav.build_literate_nav())  

docs/bin/reference_pages.py renamed to bin/reference_pages.py

@@ -24,7 +24,7 @@ theme:
 markdown_extensions:
   - footnotes
   - pymdownx.snippets:
-        base_path: ["docs/tmp"]
+        base_path: ["tmp"]
 
 extra_css:
   - css/extra_css.css