[WIP] Reusable software documentation examples

anaconda-project-lock.yml

@@ -23,7 +23,7 @@ env_specs:
     locked: false
   default:
     locked: true
-    env_spec_hash: b00fef94d2a2f103b777c177b56f90dfcf7fdc44
+    env_spec_hash: dd55ac5c70504129f612113e918f1ee56ed7deab
     platforms:
       - linux-64
       - osx-64
@@ -41,15 +41,15 @@ env_specs:
         - black=20.8b1=py_1
         - bleach=3.2.1=pyh9f0ad1d_0
         - click=7.1.2=pyh9f0ad1d_0
+        - cloudpickle=1.6.0=py_0
         - colorama=0.4.4=pyh9f0ad1d_0
-        - dataclasses=0.7=pyhb2cacf7_7
         - decorator=4.4.2=py_0
         - defusedxml=0.6.0=py_0
-        - entrypoints=0.3=pyhd8ed1ab_1003
+        - doit=0.33.1=py37hc8dfbb8_1
         - execnet=1.7.1=py_0
         - flake8=3.8.4=py_0
         - hypothesis-jsonschema=0.18.2=pyhd8ed1ab_0
-        - hypothesis=5.41.4=pyhd8ed1ab_0
+        - hypothesis=5.41.5=pyhd8ed1ab_0
         - idna=2.10=pyh9f0ad1d_0
         - importlib-metadata=3.1.1=pyhd8ed1ab_0
         - importlib_metadata=3.1.1=hd8ed1ab_0
@@ -60,7 +60,6 @@ env_specs:
         - isort=4.3.21=py37hc8dfbb8_1
         - jinja2=2.11.2=pyh9f0ad1d_0
         - json5=0.9.5=pyh9f0ad1d_0
-        - jsonschema=3.2.0=py_2
         - jupyter_client=6.1.7=py_0
         - jupyterlab=1.2.16=py_0
         - jupyterlab_pygments=0.1.2=pyh9f0ad1d_0
@@ -73,10 +72,8 @@ env_specs:
         - nest-asyncio=1.4.3=pyhd8ed1ab_0
         - networkx=2.5=py_0
         - packaging=20.7=pyhd3deb0d_0
-        - pandocfilters=1.4.2=py_1
         - parso=0.7.1=pyh9f0ad1d_0
         - pathspec=0.8.1=pyhd3deb0d_0
-        - pickleshare=0.7.5=py_1003
         - pip=20.3.1=pyhd8ed1ab_0
         - pkginfo=1.6.1=pyh9f0ad1d_0
         - prometheus_client=0.9.0=pyhd3deb0d_0
@@ -85,11 +82,10 @@ env_specs:
         - pycodestyle=2.6.0=pyh9f0ad1d_0
         - pycparser=2.20=pyh9f0ad1d_2
         - pyflakes=2.2.0=pyh9f0ad1d_0
-        - pygments=2.7.2=py_0
+        - pygments=2.7.3=pyhd8ed1ab_0
         - pyopenssl=20.0.0=pyhd8ed1ab_0
         - pyparsing=2.4.7=pyh9f0ad1d_0
         - pytest-cov=2.10.1=pyh9f0ad1d_0
-        - pytest-forked=1.2.0=pyh9f0ad1d_0
         - pytest-html=3.1.0=pyhd8ed1ab_0
         - pytest-metadata=1.11.0=pyhd3deb0d_0
         - pytest-xdist=2.1.0=py_0
@@ -105,7 +101,7 @@ env_specs:
         - sortedcontainers=2.3.0=pyhd8ed1ab_0
         - testpath=0.4.4=py_0
         - toml=0.10.2=pyhd8ed1ab_0
-        - tqdm=4.54.0=pyhd8ed1ab_0
+        - tqdm=4.54.1=pyhd8ed1ab_0
         - traitlets=5.0.5=py_0
         - twine=3.2.0=py37hc8dfbb8_1
         - typing_extensions=3.7.4.3=py_0
@@ -118,74 +114,81 @@ env_specs:
         - libblas=3.9.0=3_openblas
         - libcblas=3.9.0=3_openblas
         - liblapack=3.9.0=3_openblas
-        - pexpect=4.8.0=pyh9f0ad1d_2
-        - ptyprocess=0.6.0=py_1001
       linux-64:
         - _libgcc_mutex=0.1=conda_forge
         - _openmp_mutex=4.5=1_gnu
         - ansi2html=1.6.0=py37h89c1867_0
-        - argon2-cffi=20.1.0=py37h4abf009_2
+        - argon2-cffi=20.1.0=py37h8f50634_2
         - brotlipy=0.7.0=py37hb5d75c8_1001
-        - ca-certificates=2020.11.8=ha878542_0
-        - certifi=2020.11.8=py37h89c1867_0
+        - ca-certificates=2020.12.5=ha878542_0
+        - certifi=2020.12.5=py37h89c1867_0
         - cffi=1.14.4=py37hc58025e_1
         - chardet=3.0.4=py37he5f6b98_1008
         - cmarkgfm=0.4.2=py37h8f50634_3
         - coverage=5.3=py37h8f50634_1
         - cryptography=3.2.1=py37hc72a4ac_0
-        - dbus=1.13.6=hfdff14a_1
+        - dataclasses=0.7=py37_0
+        - dbus=1.13.18=hb2f20db_0
         - docutils=0.16=py37he5f6b98_2
-        - expat=2.2.9=he1b5a44_2
+        - entrypoints=0.3=py37hc8dfbb8_1002
+        - expat=2.2.10=he6710b0_2
         - gettext=0.19.8.1=h0b5b191_1005
         - glib=2.66.3=h9c3ff4c_1
         - icu=68.1=h58526e2_0
         - importlib_resources=3.3.0=py37h89c1867_0
-        - ipykernel=5.3.4=py37h888b3d9_1
+        - ipykernel=5.3.4=py37hc6149b9_1
         - ipython=7.19.0=py37h888b3d9_0
-        - jedi=0.17.2=py37h89c1867_1
+        - jedi=0.17.2=py37hc8dfbb8_1
         - jeepney=0.6.0=pyhd8ed1ab_0
+        - jsonschema=3.2.0=py37hc8dfbb8_1
         - jupyter_core=4.7.0=py37h89c1867_0
         - keyring=21.5.0=py37h89c1867_0
         - ld_impl_linux-64=2.35.1=hed1e6ac_0
-        - libffi=3.3=h58526e2_1
+        - libffi=3.3=h58526e2_2
         - libgcc-ng=9.3.0=h5dbcf3e_17
-        - libgfortran-ng=9.3.0=he4bcb1c_17
-        - libgfortran5=9.3.0=he4bcb1c_17
+        - libgfortran-ng=7.5.0=hae1eefd_17
+        - libgfortran4=7.5.0=hae1eefd_17
         - libglib=2.66.3=h1f3bc88_1
         - libgomp=9.3.0=h5dbcf3e_17
         - libiconv=1.16=h516909a_0
-        - libopenblas=0.3.12=pthreads_h4812303_1
-        - libsodium=1.0.18=h36c2ea0_1
+        - libopenblas=0.3.12=pthreads_hb3c22a3_1
+        - libsodium=1.0.18=h516909a_1
         - libstdcxx-ng=9.3.0=h2ae2ef3_17
         - libuv=1.40.0=hd18ef5c_0
         - markupsafe=1.1.1=py37hb5d75c8_2
-        - mistune=0.8.4=py37h4abf009_1002
+        - mistune=0.8.4=py37h8f50634_1002
         - nbconvert=6.0.7=py37h89c1867_3
         - ncurses=6.2=h58526e2_4
         - nodejs=14.15.1=h25f6087_0
         - notebook=6.1.5=py37h89c1867_0
         - numpy=1.19.4=py37h7e9df27_1
         - openssl=1.1.1h=h516909a_0
-        - pandas=1.1.4=py37h10a2094_0
+        - pandas=1.1.5=py37hdc94413_0
         - pandoc=2.11.2=h36c2ea0_0
+        - pandocfilters=1.4.3=py37h06a4308_1
         - pcre=8.44=he1b5a44_0
+        - pexpect=4.8.0=py37hc8dfbb8_1
+        - pickleshare=0.7.5=py37hc8dfbb8_1002
         - pluggy=0.13.1=py37he5f6b98_3
-        - pyrsistent=0.17.3=py37h4abf009_1
+        - ptyprocess=0.6.0=py37_1000
+        - pyinotify=0.9.6=py37hc8dfbb8_1002
+        - pyrsistent=0.17.3=py37h8f50634_1
         - pysocks=1.7.1=py37he5f6b98_2
         - pytest-asyncio=0.14.0=py37h89c1867_0
+        - pytest-forked=1.3.0=py_0
         - pytest=6.1.2=py37h89c1867_0
-        - python=3.7.8=hffdb5ce_3_cpython
+        - python=3.7.9=h7579374_0
         - pyzmq=20.0.0=py37h5a562af_1
         - readline=8.0=he28a2e2_2
         - regex=2020.11.13=py37h4abf009_0
         - secretstorage=3.3.0=py37h89c1867_0
-        - setuptools=49.6.0=py37he5f6b98_2
+        - setuptools=51.0.0=py37h06a4308_2
         - sqlite=3.34.0=h74cdb3f_0
-        - terminado=0.9.1=py37h89c1867_1
+        - terminado=0.9.1=py37hc8dfbb8_1
         - tk=8.6.10=hed695b0_1
         - tornado=6.1=py37h4abf009_0
         - typed-ast=1.4.1=py37h4abf009_1
-        - widgetsnbextension=3.5.1=py37h89c1867_4
+        - widgetsnbextension=3.5.1=py37hc8dfbb8_4
         - xz=5.2.5=h516909a_1
         - zeromq=4.3.3=h58526e2_3
         - zlib=1.2.11=h516909a_1010
@@ -194,29 +197,33 @@ env_specs:
         - appnope=0.1.2=py37hf985489_0
         - argon2-cffi=20.1.0=py37h4b544eb_2
         - brotlipy=0.7.0=py37h395d20d_1001
-        - ca-certificates=2020.11.8=h033912b_0
-        - certifi=2020.11.8=py37hf985489_0
+        - ca-certificates=2020.12.5=h033912b_0
+        - certifi=2020.12.5=py37hf985489_0
         - cffi=1.14.4=py37hc5b2277_1
         - chardet=3.0.4=py37h2987424_1008
         - cmarkgfm=0.4.2=py37h60d8a13_3
         - coverage=5.3=py37h60d8a13_1
         - cryptography=3.2.1=py37h3b7a55b_0
+        - dataclasses=0.7=pyhb2cacf7_7
         - docutils=0.16=py37h2987424_2
+        - entrypoints=0.3=pyhd8ed1ab_1003
         - icu=68.1=h74dc148_0
         - importlib_resources=3.3.0=py37hf985489_0
         - ipykernel=5.3.4=py37he01cfaa_1
         - ipython=7.19.0=py37he01cfaa_0
         - jedi=0.17.2=py37hf985489_1
+        - jsonschema=3.2.0=py_2
         - jupyter_core=4.7.0=py37hf985489_0
         - keyring=21.5.0=py37hf985489_0
         - libcxx=11.0.0=h4c3b8ed_1
-        - libffi=3.3=h74dc148_1
+        - libffi=3.3=h046ec9c_2
         - libgfortran5=9.3.0=h7cc5361_13
         - libgfortran=5.0.0=h7cc5361_13
         - libopenblas=0.3.12=openmp_h54245bb_1
         - libsodium=1.0.18=hbcb3906_1
         - libuv=1.40.0=h22f3db7_0
         - llvm-openmp=11.0.0=h73239a0_1
+        - macfsevents=0.8.1=py37h60d8a13_1001
         - markupsafe=1.1.1=py37h395d20d_2
         - mistune=0.8.4=py37h4b544eb_1002
         - nbconvert=6.0.7=py37hf985489_3
@@ -225,12 +232,17 @@ env_specs:
         - notebook=6.1.5=py37hf985489_0
         - numpy=1.19.4=py37h9ebeaaa_1
         - openssl=1.1.1h=haf1e3a3_0
-        - pandas=1.1.4=py37h9b0e0a3_0
+        - pandas=1.1.5=py37h010c265_0
         - pandoc=2.11.2=hc929b4f_0
+        - pandocfilters=1.4.2=py_1
+        - pexpect=4.8.0=pyh9f0ad1d_2
+        - pickleshare=0.7.5=py_1003
         - pluggy=0.13.1=py37h2987424_3
+        - ptyprocess=0.6.0=py_1001
         - pyrsistent=0.17.3=py37h4b544eb_1
         - pysocks=1.7.1=py37h2987424_2
         - pytest-asyncio=0.14.0=py37hf985489_0
+        - pytest-forked=1.2.0=pyh9f0ad1d_0
         - pytest=6.1.2=py37hf985489_0
         - python=3.7.8=h4f09611_3_cpython
         - pyzmq=20.0.0=py37h47fd9b3_1
@@ -251,19 +263,22 @@ env_specs:
         - argon2-cffi=20.1.0=py37hcc03f2d_2
         - atomicwrites=1.4.0=pyh9f0ad1d_0
         - brotlipy=0.7.0=py37h0013d47_1001
-        - ca-certificates=2020.11.8=h5b45459_0
-        - certifi=2020.11.8=py37h03978a9_0
+        - ca-certificates=2020.12.5=h5b45459_0
+        - certifi=2020.12.5=py37h03978a9_0
         - cffi=1.14.4=py37hd8e9650_1
         - chardet=3.0.4=py37hf50a25e_1008
         - cmarkgfm=0.4.2=py37h4ab8f01_3
         - coverage=5.3=py37h4ab8f01_1
         - cryptography=3.2.1=py37hd8e9650_0
+        - dataclasses=0.7=pyhb2cacf7_7
         - docutils=0.16=py37hf50a25e_2
+        - entrypoints=0.3=pyhd8ed1ab_1003
         - importlib_resources=3.3.0=py37h03978a9_0
         - intel-openmp=2020.3=h57928b3_311
         - ipykernel=5.3.4=py37h7b7c402_1
         - ipython=7.19.0=py37heaed05f_0
         - jedi=0.17.2=py37h03978a9_1
+        - jsonschema=3.2.0=py_2
         - jupyter_core=4.7.0=py37h03978a9_0
         - keyring=21.5.0=py37h03978a9_0
         - libblas=3.8.0=21_mkl
@@ -284,12 +299,15 @@ env_specs:
         - notebook=6.1.5=py37h03978a9_0
         - numpy=1.19.4=py37hd20adf4_1
         - openssl=1.1.1h=he774522_0
-        - pandas=1.1.4=py37h08fd248_0
+        - pandas=1.1.5=py37h08fd248_0
         - pandoc=2.11.2=h8ffe710_0
+        - pandocfilters=1.4.2=py_1
+        - pickleshare=0.7.5=py_1003
         - pluggy=0.13.1=py37hf50a25e_3
         - pyrsistent=0.17.3=py37hcc03f2d_1
         - pysocks=1.7.1=py37hf50a25e_2
         - pytest-asyncio=0.14.0=py37h03978a9_0
+        - pytest-forked=1.2.0=pyh9f0ad1d_0
         - pytest=6.1.2=py37h03978a9_0
         - python=3.7.8=h7840368_3_cpython
         - pywin32-ctypes=0.2.0=py37hc8dfbb8_1002

anaconda-project.yml

@@ -44,6 +44,7 @@ env_specs:
       - python >=3.7,<3.8.0a0
       - twine
       - wheel
+      - doit
 
   ipyelk:
     description: binder environment

dodo.py

@@ -17,6 +17,7 @@
 
 from doit.action import CmdAction
 from doit.tools import PythonInteractiveAction, config_changed
+
 from scripts import project as P
 from scripts import reporter
 from scripts import utils as U

examples/09_Doit_workflow.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# The `DODO` Development Workflow\n",
+    "\n",
+    "> Requires `doit` to be installed in the environment"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "from ipyelk.contrib.doit import DoElk"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "root = (Path() / \"..\").resolve()\n",
+    "doelk = DoElk(root=root)\n",
+    "doelk"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### The DoElk object is populated with `dodo.py` tasks"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "len(doelk.tasks)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### The transformer graphs have nodes and edges"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g, tree = doelk.transformer.source\n",
+    "print(f\"graph size \\t nodes:{len(g)} \\tedges:{len(g.edges)}\")\n",
+    "if tree:\n",
+    "    print(f\"tree size \\t nodes:{len(tree)} \\tedges:{len(tree.edges)}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Elk diagram value is populated so it should be trying to run elkjs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from IPython.display import JSON\n",
+    "\n",
+    "JSON(doelk.app.diagram.value)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}