Add doctests in utils.py (#18)

Author: harupy

pytest.ini

@@ -1,2 +1,2 @@
 [pytest]
-addopts = --verbose --color=yes --durations=5 --showlocals
+addopts = --verbose --color=yes --durations=5 --showlocals --doctest-modules sphinx_plotly_directive/utils.py

sphinx_plotly_directive/utils.py

@@ -7,12 +7,57 @@
 
 
 def save_plotly_figure(fig, path):
+    r"""
+    Save a Plotly figure.
+
+    Parameters
+    ----------
+    fig : plotly figure
+        A plotly figure to save.
+    path : str
+        A file path.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> import plotly.express as px
+    >>> import tempfile
+    >>> fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])
+    >>> path = tempfile.NamedTemporaryFile(suffix=".html").name
+    >>> save_plotly_figure(fig, path)
+    """
     fig_html = plotly.offline.plot(fig, output_type="div", include_plotlyjs="cdn", auto_open=False)
     with open(path, "w") as f:
         f.write(fig_html)
 
 
 def assign_last_line_into_variable(code, variable_name):
+    r"""
+    Save a Plotly figure.
+
+    Parameters
+    ----------
+    code : str
+        A string representing code.
+    name : str
+        A variable name.
+
+    Returns
+    -------
+    str
+        Mew code.
+
+    Examples
+    --------
+    >>> code = "a = 1\nfunc(a)"
+    >>> new_code = assign_last_line_into_variable(code, "b")
+    >>> print(new_code)
+    a = 1
+    b = func(a)
+    """
     lines = code.split("\n")
     for idx in range(len(lines) - 1, -1, -1):
         if lines[idx].strip() != "":
@@ -22,6 +67,41 @@ def assign_last_line_into_variable(code, variable_name):
 
 
 def create_directive_block(name, arguments, options, content):
+    r"""
+    Create a directive block.
+
+    Parameters
+    ----------
+    name : str
+        A directive name.
+    arguments : list of str
+        Arguments of the directive.
+    option : dict
+        Option of the directive.
+    content : list of str
+        Content of the directive.
+
+    Returns
+    -------
+    str
+        A directive block.
+
+    Examples
+    --------
+    >>> block = create_directive_block(
+    ...     "plotly",
+    ...     ["f1", "f2"],
+    ...     {"a": 0, "b": 1},
+    ...     ["l1", "l2"],
+    ... )
+    >>> print(block)
+    .. plotly:: f1 f2
+       :a: 0
+       :b: 1
+    <BLANKLINE>
+       l1
+       l2
+    """
     header = ".. {}:: ".format(name) + " ".join(arguments)
     code = "\n".join(map(str, content))