doc(plot): use |pydot.Dot| link subst; minor improvs

Author: ankostis

docs/source/index.rst

@@ -46,8 +46,8 @@ Here's how to install::
 
    pip install graphtik
 
-OR with dependencies for plotting support (and you need to install `Graphviz
-<https://graphviz.org>`_ program separately with your OS tools)::
+OR with dependencies for plotting support (and you need to install `Graphviz`_ program
+separately with your OS tools)::
 
    pip install graphtik[plot]
 

docs/source/plotting.rst

@@ -60,14 +60,14 @@ If you want all details, plot the solution::
    solution.net.plot(...)
 
 .. Note::
-   For plots, `Graphviz <https://graphviz.org>`_ program must be in your PATH,
+   For plots, `Graphviz`_ program must be in your PATH,
    and ``pydot`` & ``matplotlib`` python packages installed.
    You may install both when installing ``graphtik`` with its ``plot`` extras::
 
       pip install graphtik[plot]
 
 .. Tip::
-   The `pydot.Dot <https://pypi.org/project/pydot/>`_ instances returned by
+   The |pydot.Dot|_ instances returned by
    :meth:`.Plottable.plot()` are rendered directly in *Jupyter/IPython* notebooks
    as SVG images.
 
@@ -139,8 +139,7 @@ directive from :mod:`.sphinxext` module to embed graph-plots into your generated
          - an instance of :class:`.Plottable` (such as :class:`.NetworkOperation`,
            :class:`.Network`, :class:`.ExecutionPlan` or :class:`.Solution`);
 
-         - an already plotted ``pydot.Dot`` instance, ie, the result of a :meth:`.plot()` call
-           (see `pydot <https://github.com/pydot/pydot>`_ project).
+         - an already plotted |pydot.Dot|_ instance, ie, the result of a :meth:`.plot()` call
 
          If missing, it renders the last variable in the doctest code assigned with
          the above types.
@@ -231,7 +230,7 @@ which you may :graphtik:`reference <addmul-anchor>` with this syntax:
 .. hint::
    In this case, the ``:graphvar:`` parameter is not really needed, since
    the code contains just one variable assignment receiving a subclass
-   of :class:`.Plottable` or :class:`pydot.Dot` instance.
+   of :class:`.Plottable` or |pydot.Dot|_ instance.
 
    Additionally, the doctest code producing the *plottable* does not have to be contained
    in the *graphtik* directive.

graphtik/base.py

@@ -259,12 +259,12 @@ def plot(
             a URL to the *graphtik* legend; if it evaluates to false, none is added.
 
         :return:
-            a `pydot.Dot <https://pypi.org/project/pydot/>`_ instance
+            a |pydot.Dot|_ instance
             (for for API reference visit:
             https://pydotplus.readthedocs.io/reference.html#pydotplus.graphviz.Dot)
 
             .. Tip::
-                The :class:`pydot.Dot` instance returned is rendered directly
+                The |pydot.Dot|_ instance returned is rendered directly
                 in *Jupyter/IPython* notebooks as SVG images.
 
                 You may increase the height of the SVG cell output with

graphtik/plot.py

@@ -205,7 +205,9 @@ def build_pydot(
     legend_url="https://graphtik.readthedocs.io/en/latest/_images/GraphtikLegend.svg",
 ) -> pydot.Dot:
     """
-    Build a *Graphviz* out of a Network graph/steps/inputs/outputs and return it.
+    Build a |pydot.Dot|_ out of a Network graph/steps/inputs/outputs and return it
+
+    to be fed into `Graphviz`_ to render.
 
     See :meth:`.Plottable.plot()` for the arguments, sample code, and
     the legend of the plots.
@@ -387,10 +389,10 @@ def supported_plot_formats() -> List[str]:
 
 def render_pydot(dot: pydot.Dot, filename=None, show=False, jupyter_render: str = None):
     """
-    Plot a *Graphviz* dot in a matplotlib, in file or return it for Jupyter.
+    Render a |pydot.Dot|_ instance with `Graphviz`_ in a file/matplotlib or return it for Jupyter.
 
     :param dot:
-        the pre-built *Graphviz* :class:`pydot.Dot` instance
+        the pre-built |pydot.Dot|_ instance
     :param str filename:
         Write diagram into a file.
         Common extensions are ``.png .dot .jpg .jpeg .pdf .svg``
@@ -409,7 +411,8 @@ def render_pydot(dot: pydot.Dot, filename=None, show=False, jupyter_render: str
             netop.plot(jupyter_render={"svg_element_styles": "height: 600px; width: 100%"})
 
     :return:
-        the matplotlib image if ``show=-1``, or the `dot`.
+        the matplotlib image if ``show=-1``, or the given `dot` annotated with any
+        jupyter-rendering configurations given in `jupyter_render` parameter.
 
     See :meth:`.Plottable.plot()` for sample code.
     """