fix #385 use ipython notebook to maintain docs (#386)

* fix #385 use ipython notebook to maintain docs

* add missing plugins mknotebooks

* ignore notebook helper method

* fix view format

* update snapshot

* fix

* update

* update

* remove not related file

* remove not used files

* fix

* remove not used file

* update

* update

mkdocs.yml

@@ -41,7 +41,10 @@ nav:
   - Get Started:
       - Overview: index.md
   - Usage:
-      - How to Use: usage/how_to_use.md
+      - Basic API Usage: usage/basic-api-usage.ipynb
+      - Complex Filtering: usage/complex-filtering.ipynb
+      - Customizing Filters: usage/customizing-filters.ipynb
+      - Execute: usage/execute.ipynb
   - API Documentation:
       - ffmpeg: src/base.md
       - types: src/types.md
@@ -110,6 +113,11 @@ markdown_extensions:
 
 plugins:
   - search
+  - mknotebooks:
+      execute: false
+      timeout: 100
+      # preamble:  "<path/to/your/script>"
+      allow_errors: true
   - mkdocstrings:
       handlers:
         python:

pyproject.toml

@@ -75,6 +75,8 @@ mkdocstrings-python = "^1.8.0"
 pymdown-extensions = "^10.7"
 griffe_inherited_docstrings = "*"
 black = "*"
+ipykernel = "^6.29.4"
+mknotebooks = "*"
 
 [tool.mypy]
 exclude = "^(migrations|commands|sandbox|samples|sdk)/"

src/ffmpeg/dag/schema.py

@@ -65,6 +65,14 @@ def view(self, format: Literal["png", "svg", "dot"] = "png") -> str:
 
         return view(self.node, format=format)
 
+    def _repr_png_(self) -> bytes:  # pragma: no cover
+        with open(self.view(format="png"), "rb") as f:
+            return f.read()
+
+    def _repr_svg_(self) -> str:  # pragma: no cover
+        with open(self.view(format="svg"), "r") as f:
+            return f.read()
+
 
 @dataclass(frozen=True, kw_only=True)
 class Node(HashableBaseModel, ABC):
@@ -178,3 +186,25 @@ def upstream_nodes(self) -> set[Node]:
             output |= input.node.upstream_nodes
 
         return output
+
+    def view(self, format: Literal["png", "svg", "dot"] = "png") -> str:
+        """
+        Visualize the Node.
+
+        Args:
+            format: The format of the view.
+
+        Returns:
+            The file path of the visualization.
+        """
+        from ..utils.view import view
+
+        return view(self, format=format)
+
+    def _repr_png_(self) -> bytes:  # pragma: no cover
+        with open(self.view(format="png"), "rb") as f:
+            return f.read()
+
+    def _repr_svg_(self) -> str:  # pragma: no cover
+        with open(self.view(format="svg"), "r") as f:
+            return f.read()

src/ffmpeg/dag/tests/test_schema.py

@@ -3,7 +3,7 @@
 
 import pytest
 from syrupy.assertion import SnapshotAssertion
-from syrupy.extensions.image import PNGImageSnapshotExtension, SVGImageSnapshotExtension
+from syrupy.extensions.image import PNGImageSnapshotExtension
 from syrupy.extensions.json import JSONSnapshotExtension
 
 from ...utils.snapshot import DAGSnapshotExtenstion
@@ -104,7 +104,6 @@ def test_replace(
         )
 
 
-@pytest.mark.skip("graphviz's result is not deterministic")
 def test_stream_view(snapshot: SnapshotAssertion) -> None:
     a = SimpleNode(name="A")
     b = SimpleNode(name="B", inputs=(Stream(node=a),))
@@ -113,15 +112,18 @@ def test_stream_view(snapshot: SnapshotAssertion) -> None:
     stream = Stream(node=d)
     png = stream.view()
 
+    # test node.view()
+    stream.node.view()
+
     with open(png, "rb") as ifile:
         assert snapshot(extension_class=PNGImageSnapshotExtension) == ifile.read()
 
-    svg = stream.view(format="svg")
-
-    with open(svg, "r") as ifile:
-        assert snapshot(extension_class=SVGImageSnapshotExtension) == ifile.read()
+    # SVG and Dot Result is not stable
+    # svg = stream.view(format="svg")
+    # with open(svg, "r") as ifile:
+    #     assert snapshot(extension_class=SVGImageSnapshotExtension) == ifile.read()
 
-    dot = stream.view(format="dot")
+    # dot = stream.view(format="dot")
 
-    with open(dot, "r") as ifile:
-        assert snapshot() == ifile.read()
+    # with open(dot, "r") as ifile:
+    #     assert snapshot() == ifile.read()

src/ffmpeg/utils/view.py

@@ -59,6 +59,6 @@ def view(node: Node, format: Literal["png", "svg", "dot"]) -> str:
 
     for node in context.all_nodes:
         for idx, stream in enumerate(node.inputs):
-            graph.edge(stream.node.hex, node.hex, label=f"{stream.index} => {idx}")
+            graph.edge(stream.node.hex, node.hex, label=f"{'*' if stream.index is None else stream.index} => {idx}")
 
     return graph.render(engine="dot")