New: show examples in documentation

KyleKing · Feb 13, 2020 · 1dbac46 · 1dbac46
1 parent a4b67b6
commit 1dbac46
Show file tree

Hide file tree

Showing 12 changed files with 30 additions and 6 deletions.
diff --git a/.gitignore b/.gitignore
@@ -109,5 +109,6 @@ venv.bak/
 # ======
 # Custom
 .vscode/*
-docs/dash_charts/*.html
 *.sqlite
+
+docs/dash_charts/*
diff --git a/CHANGELOG-raw.md b/CHANGELOG-raw.md
@@ -27,6 +27,8 @@ New
 
 Changes
 ~~~~~~~
+- Update imports for newly split helpers file. [Kyle King]
+- Split helpers into charts and app utility files. [Kyle King]
 - Select port at CLI and more doc updates. [Kyle King]
 - Update requirements. [Kyle King]
 - Chg: start converting to snake_case and rethinking app structure @WIP.

diff --git a/dash_charts/utils_app.py b/dash_charts/utils_app.py
@@ -9,6 +9,8 @@
 import dash_html_components as html
 from dash.dependencies import Input, Output
 
+# FIXME: All "Returns" should have a type with ":" for pdoc
+
 ASSETS_DIR = Path(__file__).parent / 'assets'
 """Path to the static files directory."""
 

diff --git a/dodo.py b/dodo.py
@@ -9,12 +9,15 @@
 # Create list of all tasks run with `poetry run doit`
 DOIT_CONFIG = {'default_tasks': [
     'export_req', 'check_req', 'update_cl', 'document',
-    # 'commit_docs',  # Optionally comment to remove from task list
+    'open_docs',  # Comment on/off as needed
+    'commit_docs',  # Comment on/off as needed
 ]}
 
 # Set documentation paths
-DOC_DIR = Path(__file__).parent / 'docs'
+GIT_DIR = Path(__file__).parent
+DOC_DIR = GIT_DIR / 'docs'
 STAGING_DIR = DOC_DIR / PKG_NAME
+TMP_EXAMPLES_DIR = GIT_DIR / 'dash_charts/0EX'
 
 GH_PAGES_DIR = Path(__file__).parents[1] / 'Dash_Charts_gh-pages'
 if not GH_PAGES_DIR.is_dir():
@@ -28,11 +31,23 @@ def clear_docs():
             file_path.unlink()
 
 
-def copy_docs():
+def stage_documentation():
     """Copy the documentation files from the staging to the output."""
     for file_path in list(STAGING_DIR.glob('*.html')):
         shutil.copyfile(file_path, GH_PAGES_DIR / file_path.name)
 
+def stage_examples():
+    """Format the code examples as docstrings to be loaded into the documentation."""
+    TMP_EXAMPLES_DIR.mkdir(exist_ok=False)
+    (TMP_EXAMPLES_DIR / '__init__.py').write_text('"""Code Examples (documentation-only, not in `dash_charts`)."""')
+    for file_path in (GIT_DIR / 'examples').glob('*.py'):
+        content = file_path.read_text().replace('"', r'\"')
+        dest_fn = TMP_EXAMPLES_DIR / file_path.name
+        dest_fn.write_text(f'"""File: `{file_path.relative_to(GIT_DIR)}`\n```\n{content}\n```\n"""')
+
+def clear_examples():
+    """Clear the examples from within the dash_charts package."""
+    shutil.rmtree(TMP_EXAMPLES_DIR)
 
 def task_document():
     """Build the HTML documentation and push to gh-pages branch.
@@ -45,8 +60,10 @@ def task_document():
     args = f'{PKG_NAME} --html --force --template-dir "{DOC_DIR}" --output-dir "{DOC_DIR}"'
     return debug_action([
         (clear_docs, ()),
+        (stage_examples, ()),
         f'poetry run pdoc3 {args}',
-        (copy_docs, ()),
+        (clear_examples, ()),
+        (stage_documentation, ()),
     ])
 
 

diff --git a/examples/ex_alignment_chart.py → examples/alignment_chart.py b/examples/ex_alignment_chart.py → examples/alignment_chart.py
diff --git a/examples/ex_coordinate_chart.py → examples/coordinate_chart.py b/examples/ex_coordinate_chart.py → examples/coordinate_chart.py
diff --git a/examples/ex_pareto_chart.py → examples/pareto_chart.py b/examples/ex_pareto_chart.py → examples/pareto_chart.py
diff --git a/examples/ex_rolling_chart.py → examples/rolling_chart.py b/examples/ex_rolling_chart.py → examples/rolling_chart.py
diff --git a/examples/ex_Bulma_styling.py → examples/style_bulma.py b/examples/ex_Bulma_styling.py → examples/style_bulma.py
diff --git a/examples/ex_app.py → examples/tabs.py b/examples/ex_app.py → examples/tabs.py
diff --git a/poetry.lock b/poetry.lock
diff --git a/requirements.txt b/requirements.txt
@@ -55,6 +55,7 @@ flake8-printf-formatting==1.1.0
 flake8-pytest-style==0.1.3
 flake8-quotes==2.1.1
 flake8-return==1.1.1
+flake8-spellcheck==0.12.1
 flake8-sql==0.4.0
 flake8-string-format==0.2.3
 flake8-tuple==0.4.1
@@ -76,7 +77,7 @@ jinja2-pluralize==0.3.0
 macfsevents==0.8.1; sys_platform == "darwin"
 mako==1.1.1
 mando==0.6.4
-markdown==3.2
+markdown==3.2.1
 markupsafe==1.1.1
 mccabe==0.6.1
 more-itertools==8.2.0