document that doctest_skip_exe() lines should be ignored

see #172, #188, #208

CHANGES.rst

@@ -9,6 +9,8 @@ Drop Python 3.7 support (end of life 27 Jun 2023).
 
 Tag Python 3.11 and 3.12 support.
 
+Document that `doctest_skip_exe()` lines in doctest should be ignored.
+
 
 Version 0.20.1
 --------------

README.rst

@@ -102,11 +102,11 @@ Check the generated source code:
         B -> L [constraint=false]
     }
 
-Save and render the source code:
+Save and render the source code (skip/ignore any ``doctest_mark_exe()`` lines):
 
 .. code:: python
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> dot.render('doctest-output/round-table.gv').replace('\\', '/')
     'doctest-output/round-table.gv.pdf'
@@ -115,7 +115,7 @@ Save and render and view the result:
 
 .. code:: python
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> dot.render('doctest-output/round-table.gv', view=True)  # doctest: +SKIP
     'doctest-output/round-table.gv.pdf'

docs/basic_usage.rst

@@ -65,9 +65,12 @@ Use the :meth:`~.Graph.render` method to save the DOT source code
 and render it with the default ``dot`` `layout engine <DOT layouts_>`_
 (see :ref:`below <engines>` for using other layout engines).
 
+.. attention::
+    Skip/ignore any ``doctest_mark_exe()`` lines in documentation code examples.
+
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> dot.render(directory='doctest-output').replace('\\', '/')
     'doctest-output/round-table.gv.pdf'
@@ -78,7 +81,7 @@ for the rendered file type.
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> dot.render(directory='doctest-output', view=True)  # doctest: +SKIP
     'doctest-output/round-table.gv.pdf'

docs/escapes.rst

@@ -62,7 +62,7 @@ use the :func:`graphviz.escape` function
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> bs.render(format='svg', directory='doctest-output').replace('\\', '/')
     'doctest-output/literal_backslash.gv.svg'

docs/existing_files.rst

@@ -6,7 +6,7 @@ you can use the :func:`graphviz.render` function.
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> import pathlib
     >>> import graphviz

docs/formats.rst

@@ -17,7 +17,7 @@ object:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> dot = graphviz.Digraph('hello')
     >>> dot.edge('hello', 'world')

docs/integration_with_viewers.rst

@@ -25,7 +25,7 @@ might **lock** the (PDF, PNG, etc.) file for as long as the viewer is open
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> g.view(tempfile.mktemp('.gv'))  # doctest: +SKIP
     'C:\\Users\\User\\AppData\\Local\\Temp\\tmp3aoie8d0.gv.pdf'

docs/neato_no_op.rst

@@ -14,7 +14,7 @@ to pass it to the layout command:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> import graphviz
 

docs/piped_output.rst

@@ -17,7 +17,7 @@ of your :class:`.Graph` or :class:`.Digraph` object:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> h.pipe(format='pdf')[:4]
     b'%PDF'

docs/quoting.rst

@@ -57,7 +57,7 @@ parenthesis and apply normal quoting/escaping:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> d.render(directory='doctest-output').replace('\\', '/')
     'doctest-output/diamond.gv.svg'

docs/raw_dot.rst

@@ -19,14 +19,14 @@ Use the :meth:`~.Source.render` method to save and render it:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> src.render('doctest-output/holy-grenade.gv').replace('\\', '/')
     'doctest-output/holy-grenade.gv.pdf'
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> src.render('doctest-output/holy-grenade.gv', view=True).replace('\\', '/')  # doctest: +SKIP
     'doctest-output/holy-grenade.gv.pdf'

docs/subgraphs_and_clusters.rst

@@ -62,7 +62,7 @@ and ``encoding``:
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> p = graphviz.Graph('parent', directory='doctest-output')
 

docs/unflatten.rst

@@ -16,7 +16,7 @@ use the :meth:`~.Graph.unflatten` method.
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> w.view()  # doctest: +SKIP
 
@@ -34,7 +34,7 @@ use the :meth:`~.Graph.unflatten` method.
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> u.view()  # doctest: +SKIP
 
@@ -54,7 +54,7 @@ with the same basic API as :class:`.Graph` or :class:`.Digraph` objects
 
 .. doctest::
 
-    >>> doctest_mark_exe()
+    >>> doctest_mark_exe()  # skip this line
 
     >>> u.view()  # doctest: +SKIP