REFACT: PLOT OPs HTML LABEL

Author: ankostis

.vscode/cspell.json

@@ -27,6 +27,7 @@
         "autodoc",
         "autodocs",
         "baumgartner",
+        "BGCOLOR",
         "blackline",
         "boltons",
         "bools",

CHANGES.rst

@@ -16,6 +16,14 @@ Changelog
 %%%%%%%%%
 
 
+v5.8.0 (8 Apr 2020, @ankostis): Plot job, fix RTD deps
+======================================================
++ FEAT(PLOT): plots are now fully configurable with *graph*, *node* & *edge*
+  ("non-private") attributes, conveyed with the `networkx` graph given to plot routine.
+
++ drop(plot): don't suppress the grafting of the title in netop images.
+
+
 v5.7.1 (7 Apr 2020, @ankostis): Plot job, fix RTD deps
 ======================================================
 + ENH(PLOT): Operation tooltips now show function sources.

docs/source/arch.rst

@@ -359,17 +359,26 @@ Architecture
         A :class:`.Plotter` is responsible for rendering `plottable`\s as images.
         It is the `installed plotter` that does that, unless overridden in a
         :meth:`.Plottable.plot()` call.
-        Plotters can be customized by :ref:`various means <plot-customizations>`.
+        Plotters can be customized by :ref:`various means <plot-customizations>`,
+        such `plot styles`.
 
     installed plotter
-        The `plotter` currently installed in the respective `graphtik configuration`
-        with one of :func:`.installed_plotter` or :func:`.set_installed_plotter`
-        functions - this term implies also any :ref:`plot-customizations`
-        done on the installed plotter's :class:`.plot.Style` attribute.
+    default installed plotter
+        The `plotter` currently installed "in-context" of the respective `graphtik
+        configuration` - this term implies also any :ref:`plot-customizations`
+        done on the installed plotter (such as `plot styles`).
+
+        Installation happens by calling one of :func:`.installed_plotter` or
+        :func:`.set_installed_plotter` functions.
 
         The **default** *installed plotter* is the plotter instance that this project
         comes pre-configured with, ie, when no *plot-customizations* have yet happened.
 
+    plot styles
+        The attributes of :class:`.plot.Style` class.
+        The actual styles in-use are those in the :attr:`.Plotter.style` attribute
+        of the `installed plotter`.
+
 
 .. default-role:: obj
 .. |v410-flowchart| raw:: html

docs/source/conf.py

@@ -30,7 +30,7 @@
 from sphinx.application import Sphinx
 
 from graphtik.base import func_sourcelines
-from graphtik.plot import Plotter, Style, get_installed_plotter, set_installed_plotter
+from graphtik import plot
 
 
 log = logging.getLogger(__name__)
@@ -101,10 +101,14 @@
     "gg": ("https://github.com/pygraphkit/graphtik/issues/%s", "#"),
 }
 
-# Plot graphs with links to docs.
-plotter = get_installed_plotter().copy()
-plotter.style.kw_op_url = {"url_format": "../reference.html#%s", "target": "_top"}
-set_installed_plotter(plotter)
+# Save dot files, for debug.
+graphtik_save_dot_files = True
+
+# Plot graphtik SVGs with links to docs.
+#
+plotter = plot.get_installed_plotter().copy()
+plotter.style.py_item_url_format = "../reference.html#%(dot_path)s"
+plot.set_installed_plotter(plotter)
 
 github_slug = "pygraphkit/graphtik"
 try:

docs/source/plotting.rst

@@ -324,7 +324,7 @@ Plot customizations
    You may customize the styles and/or *plotter* behavior with various methods,
    ordered by breadth of the effects (most broadly effecting method at the top):
 
-   1. Get and modify in-place the styles of the *default* :term:`installed plotter`,
+   1. Get and modify in-place the styles of the :term:`default installed plotter`,
       like that::
 
          get_installed_plotter().style.kw_op["fillcolor"] = "purple"

graphtik/base.py

@@ -208,8 +208,7 @@ def func_source(fn, default=..., human=None) -> Optional[Tuple[str, int]]:
         If given, better be a 2-tuple respecting types,
         or ``...``, to raise.
     :param human:
-        when true, partials denote their args like ``$fn(a=1, ...)`` in the returned text,
-        otherwise, just the (fqd-)name, appropriate for IDs.
+        when true, denote builtins like python does
     """
     import inspect
 
@@ -450,13 +449,30 @@ def plot(
             No need to quote it, handled by the plotter, downstream.
         :param str graph:
             (optional) A :class:`nx.Digraph` with overrides to merge with the graph provided
-            by underlying plottables (depending of course on the :term:`installed plotter`).
-            It may contain "public" graph, node & edge attributes eventually reaching
-            `Graphviz`_.
+            by underlying plottables (translated by the :term:`installed plotter`).
+
+            It may contain "public" or "private *graph*, *node* & *edge* attributes:
+
+            - "private" attributes: those starting with underscore(``_``),
+              handled by :term:`plotter`:
+
+              - ``_source`` *(graph)*: a non user-overridable attribute with values
+                used to select plotter-styles::
+
+                    netop | net | plan | solution | <'_source` missing>
+              - ``_fn_link_target`` & ``_fn_link_target`` *(node)*: if truthy,
+                override result 2-tuple of :meth:`_get_fn_link()`.
+              - ``_op_tooltip`` & ``_fn_tooltip`` *(node)*: if truthy,
+                override those derrived from :meth:`_make_op_tooltip()` &
+                :meth:`_make_op_tooltip()`.
+
+            - "public" attributes: reaching `Graphviz`_ as-is.
+
+              .. Note::
+
+                Remember to escape those values as `Graphviz`_ HTML-Like strings
+                (use :func:`.plot.graphviz_html_string()`).
 
-            .. Note::
-                Remember to properly escape values for `Graphviz`_
-                e.g. with :func:`html.escape()` or :func:`.plot.quote_dot_word()`.
         :param inputs:
             an optional name list, any nodes in there are plotted
             as a "house"
@@ -552,7 +568,7 @@ def plot(
         fontname=italic;
         label=<netop>;
         splines=ortho;
-        <a> [fillcolor=wheat, shape=invhouse, style=filled, tooltip=<(int) 1>];
+        <a> [fillcolor=wheat, shape=invhouse, style=filled, tooltip="(int) 1"];
         ...
 
         """

graphtik/netop.py

@@ -247,14 +247,15 @@ def withset(
 
     def prepare_plot_args(self, plot_args: PlotArgs) -> PlotArgs:
         """Delegate to network if last-plan does not exist. """
-        from .plot import quote_dot_word
+        from .plot import graphviz_html_string
 
         plottable = self.last_plan or self.net
         plot_args = plot_args.with_defaults(name=self.name)
         plot_args = plottable.prepare_plot_args(plot_args)
         assert plot_args.graph, plot_args
 
-        plot_args.graph.graph.setdefault("label", quote_dot_word(self.name))
+        plot_args.graph.graph.setdefault("label", graphviz_html_string(self.name))
+        plot_args.graph.graph["_source"] = "netop"
 
         return plot_args
 

graphtik/network.py

@@ -341,7 +341,10 @@ def prepare_plot_args(self, plot_args: PlotArgs) -> PlotArgs:
         """delegate to plan, with solution"""
         name = f"solution-x{len(self.plan.net.graph.nodes)}-nodes"
         plot_args = plot_args.with_defaults(name=name, solution=self)
-        return self.plan.prepare_plot_args(plot_args)
+        plot_args = self.plan.prepare_plot_args(plot_args)
+        plot_args.graph.graph["_source"] = "solution"
+
+        return plot_args
 
 
 class _DataNode(str):
@@ -507,6 +510,7 @@ def prepare_plot_args(self, plot_args: PlotArgs) -> PlotArgs:
         if self.dag.nodes != graph.nodes:
             clusters = {n: "after pruning" for n in self.dag.nodes}
 
+        graph.graph["_source"] = "plan"
         return plot_args.with_defaults(
             name=f"plan-x{len(graph.nodes)}-nodes",
             steps=self.steps,
@@ -941,6 +945,7 @@ def prepare_plot_args(self, plot_args: PlotArgs) -> PlotArgs:
             inputs=self.needs,
             outputs=self.provides,
         )
+        plot_args.graph.graph["_source"] = "net"
         return plot_args
 
     def _append_operation(self, graph, operation: Operation):