[WIP] Initial python api reference docs

.github/workflows/ci.yml

@@ -4,9 +4,11 @@ on:
   push:
     branches:
       - master
+      - 0.3.x
   pull_request:
     branches:
       - master
+      - 0.3.x
 
 env:
   PYTHONIOENCODING: utf-8

.gitignore

@@ -157,10 +157,6 @@ py_src/ipyelk/labextension/*.tgz
 # -------------
 **/coverage/
 
-# generated files
-py_src/ipyelk/schema/*.json
-py_src/ipyelk/labextension/
-
 # editors
 .idea/
 .vscode/

.readthedocs.yml

@@ -2,7 +2,6 @@ version: 2
 
 sphinx:
   configuration: docs/conf.py
-
 conda:
   environment: docs/rtd.yml
 

docs/index.md

@@ -6,3 +6,10 @@
 changelog
 contributing
 ```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:titlesonly:
+reference/index
+```

docs/reference/index.md

@@ -0,0 +1,9 @@
+# API Reference
+
+This page describe the overall API for ipyelk.
+
+```{toctree}
+:maxdepth: 2
+widgets
+transformers
+```

docs/reference/transformers.md

@@ -0,0 +1,24 @@
+# Transformers
+
+The goal of transformers is to take some generalized source and generate valid elk json
+to pass to an ElkDiagram widget for layout.
+
+## Transformer
+
+```{eval-rst}
+.. currentmodule:: ipyelk.transform
+.. autoclass:: EdgeMap
+.. autoclass:: ElkTransformer
+    :members:
+```
+
+## NetworkX Transformer
+
+```{eval-rst}
+.. currentmodule:: ipyelk.nx.transformer
+
+
+.. autoclass:: XELK
+    :show-inheritance:
+    :members:
+```

docs/reference/widgets.md

@@ -0,0 +1,25 @@
+# Widgets
+
+## Diagram Widget
+
+```{eval-rst}
+.. currentmodule:: ipyelk.diagram.elk_widget
+.. autoclass:: ipyelk.diagram.elk_widget.ElkDiagram
+    :members:
+```
+
+## App Widget
+
+```{eval-rst}
+.. currentmodule:: ipyelk.app
+.. autoclass:: ipyelk.app.Elk
+    :members:
+```
+
+## Layout Widget
+
+```{eval-rst}
+.. currentmodule:: ipyelk.layouting.elkjs
+.. autoclass:: ipyelk.layouting.elkjs.ElkJS
+    :members:
+```

docs/rtd.yml

@@ -10,3 +10,5 @@ dependencies:
   - python >=3.7,<3.8
   - sphinx
   - sphinx-autodoc-typehints
+  - pip:
+      - -e ..

dodo.py

@@ -142,7 +142,7 @@ def task_binder():
 
 def task_env():
     """prepare project envs"""
-    envs = ["default", "atest"]
+    envs = ["default", "atest", "docs"]
     for i, env in enumerate(envs):
         file_dep = [P.PROJ_LOCK, P.OK_PREFLIGHT_CONDA]
         if P.FORCE_SERIAL_ENV_PREP and i:
@@ -231,6 +231,19 @@ def task_setup():
             P.OK_LABEXT,
         )
 
+def task_setup_docs():
+    _install = ["--no-deps", "--ignore-installed", "-vv", "-e", "."]
+    yield _ok(
+        dict(
+            name="docs py setup",
+            file_dep=[P.OK_ENV["docs"]],
+            actions=[
+                [*P.APR, "docs", *P.PIP, "install", *_install],
+                [*P.APR, "docs", *P.PIP, "check"],
+            ],
+        ),
+        P.OK_DOCS_PIP_INSTALL
+    )
 
 if not P.TESTING_IN_CI:
 
@@ -583,7 +596,7 @@ def task_docs():
     """build the docs (mostly as readthedocs would)"""
     yield dict(
         name="sphinx",
-        file_dep=[P.DOCS_CONF, *P.ALL_PY_SRC, *P.ALL_MD],
+        file_dep=[P.DOCS_CONF, *P.ALL_PY_SRC, *P.ALL_MD, P.OK_DOCS_PIP_INSTALL],
         targets=[P.DOCS_BUILDINFO],
         actions=[[*P.APR_DOCS, "docs"]],
     )
@@ -594,7 +607,7 @@ def task_watch_docs():
     yield dict(
         uptodate=[lambda: False],
         name="sphinx-autobuild",
-        file_dep=[P.DOCS_BUILDINFO, *P.ALL_MD],
+        file_dep=[P.DOCS_BUILDINFO, *P.ALL_MD, P.OK_DOCS_PIP_INSTALL],
         actions=[
             LongRunning(
                 [*P.APR_DOCS, "sphinx-autobuild", P.DOCS, P.DOCS_BUILD], shell=False

py_src/ipyelk/app.py

@@ -11,7 +11,19 @@
 
 
 class Elk(W.VBox, StyledWidget):
-    """ An Elk diagramming widget """
+    """An Elk diagramming widget to help coordinate the
+    :py:class:`~ipyelk.diagram.elk_widget.ElkDiagram` and
+    :py:class:`~ipyelk.transform.ElkTransformer`
+
+    Attributes
+    ----------
+
+    transformer: :py:class:`~ipyelk.diagram.elk_widget.ElkDiagram`
+        Transformer to convert source objects into valid elk json value
+    diagram: :py:class:`~ipyelk.diagram.elk_widget.ElkDiagram`
+
+    :param toolbar: Toolar for widget
+    """
 
     transformer: ElkTransformer = T.Instance(ElkTransformer)
     diagram: ElkDiagram = T.Instance(ElkDiagram)

py_src/ipyelk/diagram/elk_widget.py

@@ -3,7 +3,7 @@
 # Copyright (c) 2021 Dane Freeman.
 # Distributed under the terms of the Modified BSD License.
 
-from typing import List
+from typing import Dict, List, Tuple
 
 import traitlets as T
 from ipywidgets import CallbackDispatcher, DOMWidget, widget_serialization
@@ -16,7 +16,28 @@
 
 
 class ElkDiagram(DOMWidget):
-    """Jupyterlab widget for interacting with ELK diagrams"""
+    """Jupyterlab widget for displaying and interacting with diagrams generated
+    from elk json.
+
+    Setting the instance's `value` traitlet to valid `elk json
+    <https://www.eclipse.org/elk/documentation/tooldevelopers/
+    graphdatastructure/jsonformat.html>`_  will call the `elkjs layout method
+    <https://github.com/kieler/elkjs>`_ and display the returned `mark_layout`
+    using `sprotty <https://github.com/eclipse/sprotty>`_.
+
+    :ivar value: Input elk json
+    :vartype value: Dict
+    :ivar mark_layout: Resulting layout from current layouter e.g. elkjs
+    :vartype mark_layout: Dict
+    :ivar selected: elk ids of selected marks
+    :vartype selected: Tuple[str]
+    :ivar hovered: elk id of currently hovered mark
+    :vartype hovered: str
+    :ivar layouter: A layouter to add position and sizes to marks in the incoming
+        elk json
+    :vartype layouter: ElkJS
+
+    """
 
     _model_name = T.Unicode("ELKDiagramModel").tag(sync=True)
     _model_module = T.Unicode(EXTENSION_NAME).tag(sync=True)
@@ -29,10 +50,10 @@ class ElkDiagram(DOMWidget):
     defs = T.Dict(value_trait=T.Instance(Def), kw={}).tag(
         sync=True, **def_serialization
     )
-    mark_layout = T.Dict().tag(sync=True)
-    selected = T.Tuple().tag(sync=True)
-    hovered = T.Unicode(allow_none=True, default_value=None).tag(sync=True)
-    layouter = T.Instance(ElkJS, kw={}).tag(sync=True, **widget_serialization)
+    mark_layout: Dict = T.Dict().tag(sync=True)
+    selected: Tuple = T.Tuple().tag(sync=True)
+    hovered: str = T.Unicode(allow_none=True, default_value=None).tag(sync=True)
+    layouter: ElkJS = T.Instance(ElkJS, kw={}).tag(sync=True, **widget_serialization)
 
     def __init__(self, *value, **kwargs):
         if value:

py_src/ipyelk/labextension/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@jupyrdf/jupyter-elk",
+  "version": "1.0.1",
+  "description": "ElkJS widget for Jupyter",
+  "keywords": [
+    "jupyter",
+    "jupyterlab",
+    "jupyterlab-extension",
+    "widgets"
+  ],
+  "homepage": "https://github.com/jupyrdf/ipyelk",
+  "bugs": {
+    "url": "https://github.com/jupyrdf/ipyelk/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Dane Freeman",
+  "files": [
+    "{lib,style,src}/**/*.{.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf,css}",
+    "LICENSE.txt",
+    "COPYRIGHT.md",
+    "third-party/**/*"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "style": "style/index.css",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jupyrdf/ipyelk"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "proseWrap": "always",
+    "printWidth": 88
+  },
+  "scripts": {
+    "bootstrap": "jlpm --prefer-offline --ignore-optional --ignore-scripts && jlpm clean && jlpm schema && jlpm lint && jlpm build",
+    "build": "jlpm build:ts && jlpm build:ext",
+    "build:ts": "tsc -b",
+    "build:ext": "jupyter labextension build .",
+    "clean": "rimraf ./lib ./py_src/ipyelk/schema/elkschema.json ./py_src/ipyelk/labextension",
+    "watch": "jlpm build:ts --watch --preserveWatchOutput",
+    "schema": "ts-json-schema-generator --tsconfig ./tsconfig.json --type AnyElkNode --no-type-check --expose all --path ./src/elkschema.ts -o ./py_src/ipyelk/schema/elkschema.json",
+    "lint": "jlpm lint:prettier",
+    "lint:prettier": "prettier --write --list-different \"*.{json,yml,md}\" \"{src,style,py_src,.github,examples,docs}/**/*.{ts,tsx,js,jsx,css,json,md,yml}\""
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.1.13",
+    "sprotty-elk": "0.9.0"
+  },
+  "devDependencies": {
+    "@jupyter-widgets/base": "4",
+    "@jupyter-widgets/controls": "3",
+    "@jupyter-widgets/jupyterlab-manager": "3",
+    "@jupyterlab/application": "3",
+    "@jupyterlab/builder": "^3.0.1",
+    "@jupyterlab/theme-dark-extension": "3",
+    "@jupyterlab/theme-light-extension": "3",
+    "@types/lodash": "^4.14.162",
+    "prettier": "^1.9.1",
+    "rimraf": "^3.0.2",
+    "snabbdom": "~0.6.6",
+    "ts-json-schema-generator": "^0.83.2",
+    "typescript": "~4.1.3"
+  },
+  "peerDependencies": {
+    "@jupyter-widgets/base": "4",
+    "@jupyter-widgets/controls": "3",
+    "@jupyter-widgets/jupyterlab-manager": "3"
+  },
+  "sideEffects": [
+    "style/*.css"
+  ],
+  "jupyterlab": {
+    "extension": "lib/plugin",
+    "outputDir": "py_src/ipyelk/labextension",
+    "sharedPackages": {
+      "@jupyter-widgets/base": {
+        "bundled": false,
+        "singleton": true
+      }
+    },
+    "_build": {
+      "load": "static/remoteEntry.71cdf6b00b374443398e.js",
+      "extension": "./extension",
+      "style": "./style"
+    }
+  }
+}