Merge branch 'main' into 418-picker

.github/workflows/make-docs.yml

@@ -25,7 +25,7 @@ jobs:
           path: plugins/${{ inputs.package }}/dist/
 
       - name: Install requirements
-        run: pip install -r plugins/${{ inputs.package }}/requirements.txt
+        run: pip install -r plugins/${{ inputs.package }}/sphinx-requirements.txt
 
       - name: Install wheel
         run: pip install plugins/${{ inputs.package }}/dist/*.whl

.github/workflows/modified-plugin.yml

@@ -36,6 +36,7 @@ jobs:
             plotly-express:
               - plugins/plotly-express/**
               - .github/workflows/test-*.yml
+              - sphinx_ext/*
             plotly:
               - plugins/plotly/**
               - .github/workflows/test-*.yml

.pre-commit-config.yaml

@@ -15,15 +15,16 @@ repos:
     rev: v1.1.334
     hooks:
       - id: pyright
-        files: plugins.*\/src.*\.py
+        files: (plugins\/.*\/src|sphinx_ext)\/.*\.py
         additional_dependencies:
           [
             pandas,
             deephaven-core,
             plotly,
             json-rpc,
             matplotlib,
-            deephaven-plugin-utilities
+            deephaven-plugin-utilities,
+            sphinx,
           ]
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.2.2

plugins/plotly-express/README.md

@@ -60,7 +60,7 @@ Docs can be built locally
 
 Install the necessary dependencies:
 ```shell
-pip install -r requirements.txt
+pip install -r sphinx-requirements.txt
 pip install dist/deephaven_plugin_plotly_express-*.whl
 ```
 then run the docs make script:

plugins/plotly-express/conf.py

@@ -5,6 +5,8 @@
 import os
 import sys
 
+sys.path.append(os.path.abspath("../../sphinx_ext"))
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -22,6 +24,7 @@
     "sphinx.ext.napoleon",
     "sphinx_markdown_builder",
     "sphinx_autodoc_typehints",
+    "deephaven_autodoc",
 ]
 
 source_suffix = [".rst", ".md"]  # Can use either rst or markdown files as input
@@ -34,7 +37,6 @@
 
 # options for sphinx_autodoc_typehints
 always_use_bars_union = True
-typehints_defaults = "comma"
 
 from deephaven_server import Server
 

plugins/plotly-express/docs/area.md

@@ -14,5 +14,5 @@ Area plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.area
+.. dhautofunction:: deephaven.plot.express.area
 ```

plugins/plotly-express/docs/bar.md

@@ -15,5 +15,5 @@ Bar plots have limitations and are not suitable for certain scenarios. They are
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.bar
+.. dhautofunction:: deephaven.plot.express.bar
 ```

plugins/plotly-express/docs/box.md

@@ -13,5 +13,5 @@ Box plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.box
+.. dhautofunction:: deephaven.plot.express.box
 ```

plugins/plotly-express/docs/candlestick.md

@@ -17,5 +17,5 @@ Candlestick plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.candlestick
+.. dhautofunction:: deephaven.plot.express.candlestick
 ```

plugins/plotly-express/docs/funnel-area.md

@@ -13,5 +13,5 @@ Funnel area plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.funnel_area
+.. dhautofunction:: deephaven.plot.express.funnel_area
 ```

plugins/plotly-express/docs/funnel.md

@@ -12,5 +12,5 @@ Funnel plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.funnel
+.. dhautofunction:: deephaven.plot.express.funnel
 ```

plugins/plotly-express/docs/histogram.md

@@ -13,5 +13,5 @@ Histogram plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.histogram
+.. dhautofunction:: deephaven.plot.express.histogram
 ```

plugins/plotly-express/docs/icicle.md

@@ -13,5 +13,5 @@ Icicle plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.icicle
+.. dhautofunction:: deephaven.plot.express.icicle
 ```

plugins/plotly-express/docs/layer-plots.md

@@ -7,5 +7,5 @@ To "layer" or "stack" multiple plots on top of each other, use the `layer` funct
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.layer
+.. dhautofunction:: deephaven.plot.express.layer
 ```

plugins/plotly-express/docs/line-3d.md

@@ -16,5 +16,5 @@ Alternatives to 3D line plots include:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.line_3d
+.. dhautofunction:: deephaven.plot.express.line_3d
 ```

plugins/plotly-express/docs/line-polar.md

@@ -13,5 +13,5 @@ Polar line plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.line_polar
+.. dhautofunction:: deephaven.plot.express.line_polar
 ```

plugins/plotly-express/docs/line-ternary.md

@@ -11,5 +11,5 @@ Ternary line plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.line_ternary
+.. dhautofunction:: deephaven.plot.express.line_ternary
 ```

plugins/plotly-express/docs/line.md

@@ -398,5 +398,5 @@ scatter_plot_opacity = dx.scatter(
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.line
+.. dhautofunction:: deephaven.plot.express.line
 ```

plugins/plotly-express/docs/ohlc.md

@@ -15,5 +15,5 @@ OHLC (Open-High-Low-Close) plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.ohlc
+.. dhautofunction:: deephaven.plot.express.ohlc
 ```

plugins/plotly-express/docs/pie.md

@@ -16,5 +16,5 @@ Limitations of pie plots include:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.pie
+.. dhautofunction:: deephaven.plot.express.pie
 ```

plugins/plotly-express/docs/scatter-3d.md

@@ -134,5 +134,5 @@ scatter_plot_color_column = dx.scatter_3d(
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.scatter_3d
+.. dhautofunction:: deephaven.plot.express.scatter_3d
 ```

plugins/plotly-express/docs/scatter-polar.md

@@ -13,5 +13,5 @@ Polar scatter plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.scatter_polar
+.. dhautofunction:: deephaven.plot.express.scatter_polar
 ```

plugins/plotly-express/docs/scatter-ternary.md

@@ -13,5 +13,5 @@ Ternary scatter plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.scatter_ternary
+.. dhautofunction:: deephaven.plot.express.scatter_ternary
 ```

plugins/plotly-express/docs/scatter.md

@@ -445,5 +445,5 @@ scatter_plot_opacity = dx.scatter(
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.scatter
+.. dhautofunction:: deephaven.plot.express.scatter
 ```

plugins/plotly-express/docs/strip.md

@@ -14,5 +14,5 @@ Strip plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.strip
+.. dhautofunction:: deephaven.plot.express.strip
 ```

plugins/plotly-express/docs/sub-plots.md

@@ -7,5 +7,5 @@ Multiple sub plots can be combined into one plot using the `make_subplots` funct
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.make_subplots
+.. dhautofunction:: deephaven.plot.express.make_subplots
 ```

plugins/plotly-express/docs/sunburst.md

@@ -12,5 +12,5 @@ Sunburst plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.sunburst
+.. dhautofunction:: deephaven.plot.express.sunburst
 ```

plugins/plotly-express/docs/timeline.md

@@ -7,5 +7,5 @@ Timeline plots in offer a means to visualize time-related data, displaying event
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.timeline
+.. dhautofunction:: deephaven.plot.express.timeline
 ```

plugins/plotly-express/docs/treemap.md

@@ -13,5 +13,5 @@ Treemap plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.treemap
+.. dhautofunction:: deephaven.plot.express.treemap
 ```

plugins/plotly-express/docs/violin.md

@@ -14,5 +14,5 @@ Violin plots are useful for:
 
 ## API Reference
 ```{eval-rst}
-.. autofunction:: deephaven.plot.express.violin
+.. dhautofunction:: deephaven.plot.express.violin
 ```

plugins/plotly-express/make_docs.py

@@ -1,45 +1,79 @@
+from __future__ import annotations
+
 import os
+import contextlib
+from typing import IO, Generator
 
 BUILT_DOCS = "docs/build/markdown"
 
-# save original directory so we can return to it
-cwd = os.getcwd()
 
-# change to the directory of this file
-dirname = os.path.dirname(__file__)
-os.chdir(dirname)
+@contextlib.contextmanager
+def pushd() -> None:
+    """
+    Change to the script directory, and return to the original directory when done.
+    """
+    # save original directory so we can return to it
+    cwd = os.getcwd()
 
-os.system("make clean")
+    # change to the directory of this file
+    dirname = os.path.dirname(__file__)
+    if dirname:
+        os.chdir(dirname)
 
-print("Building markdown")
-os.system("make markdown")
+    try:
+        yield
+    finally:
+        # ensure we always return to the original directory, even if an exception is raised
+        os.chdir(cwd)
 
-print("Copying assets")
-os.system(f"cp -r docs/_assets {BUILT_DOCS}/_assets")
-os.system(f"cp docs/sidebar.json {BUILT_DOCS}/sidebar.json")
 
-os.system(f"rm {BUILT_DOCS}/index.md")
+def md_files() -> Generator[str, None, None]:
+    """
+    Walk the built docs directory and yield the path to each markdown file.
 
-try:
-    # go through each markdown file, look for ### deephaven.plot.express then add the syntax block
+    Returns:
+        Generator[str, None, None]: The path to each markdown file.
+    """
     for root, dirs, files in os.walk(BUILT_DOCS):
         for file in files:
             if file.endswith(".md"):
-                with open(os.path.join(root, file), "r") as f:
-                    lines = f.readlines()
-                with open(os.path.join(root, file), "w") as f:
-                    for line in lines:
-                        if "### deephaven.plot.express." in line:
-                            # remove escaped \* with * as it's not needed when in a code block
-                            line = line.replace("\\*", "*")
-                            # first add the lines here
-                            line = line.replace("### deephaven.plot.express.", "")
-                            before = "<Syntax>\n\n```python\n"
-                            after = "```\n\n</Syntax>\n"
-                            line = before + line + after
-                            # then here
-                        f.write(line)
-
-finally:
-    # ensure we always return to the original directory, even if an exception is raised
-    os.chdir(cwd)
+                yield os.path.join(root, file)
+
+
+def md_lines() -> Generator[tuple[IO, str], None, None]:
+    """
+    Open each markdown file and yield the file object and each line in the file.
+
+    Returns:
+        Generator[tuple[IO, str], None, None]: The file object and each line in the file.
+    """
+    for file in md_files():
+        with open(file, "r") as f:
+            lines = f.readlines()
+        with open(file, "w") as f:
+            for line in lines:
+                yield f, line
+
+
+with pushd():
+    os.system("make clean")
+
+    print("Building markdown")
+    os.system("make markdown")
+
+    print("Copying assets")
+    os.system(f"cp -r docs/_assets {BUILT_DOCS}/_assets")
+    os.system(f"cp docs/sidebar.json {BUILT_DOCS}/sidebar.json")
+
+    os.system(f"rm {BUILT_DOCS}/index.md")
+
+    for f, line in md_lines():
+        if line.startswith("<!-- <ParamTable param={{") and line.endswith(
+            "}} /> -->\n"
+        ):
+            # remove the comment markers
+            # these are added in deephaven_autodoc.py to prevent special characters from being escaped
+            # by the markdown renderer
+            line = line.replace("<!-- ", "")
+            line = line.replace(" -->", "")
+        f.write(line)

plugins/plotly-express/sphinx-requirements.txt

@@ -0,0 +1,6 @@
+deephaven-server
+Sphinx
+myst-parser
+sphinx-markdown-builder
+sphinx-autodoc-typehints
+typing_extensions;python_version<'3.11'