docs: function autodocs embedded in docs (#527)

Fixes #501 

No github action in this pr, but this allows a local build of docs as a
starting point

directions to test - from README.md in plotly-express folder


Docs can be built locally from the plotle-express folder

Install the necessary dependencies:
```shell
pip install -r requirements.txt
pip install ../dist/deephaven_plugin_plotly_express-*.whl
```
then run the docs make script:
```shell
python make_docs.py
```

plugins/plotly-express/.gitignore

@@ -5,4 +5,5 @@ dist/
 *.egg-info/
 .idea
 .DS_store
-__pycache__/
+__pycache__/
+/docs/build/

plugins/plotly-express/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -c .
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = docs/build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

plugins/plotly-express/README.md

@@ -54,3 +54,19 @@ source = new_table(
 
 fig = dx.bar(table=source, x="Categories", y="Values")
 ```
+
+## Docs
+Docs can be built locally
+
+Install the necessary dependencies:
+```shell
+pip install -r requirements.txt
+pip install dist/deephaven_plugin_plotly_express-*.whl
+```
+then run the docs make script:
+```shell
+python make_docs.py
+```
+
+The files will be built into `docs/build/markdown`.
+Note that these built files should not be committed to the repository.

plugins/plotly-express/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "deephaven"
+copyright = "2024, Deephaven Data Labs"
+author = "Deephaven Data Labs"
+release = "0.7.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_markdown_builder",
+    "sphinx_autodoc_typehints",
+]
+
+source_suffix = [".rst", ".md"]  # Can use either rst or markdown files as input
+
+# show hints in the description so that the function definition is not cluttered
+autodoc_typehints = "description"
+
+# exclude build directory
+exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
+
+# options for sphinx_autodoc_typehints
+always_use_bars_union = True
+typehints_defaults = "comma"
+
+from deephaven_server import Server
+
+s = Server(port=10075)
+s.start()

plugins/plotly-express/docs/area.md

@@ -10,3 +10,9 @@ Area plots are useful for:
 4. **Time Series Analysis**: For time-dependent data, area plots are valuable for displaying changes in categorical contributions and overall trends over time.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.area
+```

plugins/plotly-express/docs/bar.md

@@ -12,3 +12,8 @@ Advantages of bar plots include:
 Bar plots have limitations and are not suitable for certain scenarios. They are not ideal for continuous data, ineffective for multi-dimensional data exceeding two dimensions, and unsuitable for time-series data trends. Additionally, they become less practical with extremely sparse datasets and are inadequate for representing complex interactions or correlations among multiple variables.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.bar
+```

plugins/plotly-express/docs/box.md

@@ -10,3 +10,8 @@ Box plots are useful for:
 4. **Robustness**: Box plots are robust to extreme values and data skewness, providing a reliable means of visualizing data distributions even in the presence of outliers or non-normal data.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.box
+```

plugins/plotly-express/docs/candlestick.md

@@ -14,3 +14,8 @@ Candlestick plots are useful for:
 4. **Visualizing Variation in Price Data**: Candlestick charts offer a visually intuitive way to represent variability in price data, making them valuable for traders and analysts who prefer a visual approach to data analysis.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.candlestick
+```

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

@@ -10,3 +10,8 @@ Funnel area plots are useful for:
 4. **Data Funneling**: When representing data where values funnel through stages or categories.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.funnel_area
+```

plugins/plotly-express/docs/funnel.md

@@ -8,3 +8,9 @@ Funnel plots are useful for:
 2. **Sequential Processes**: Funnel plots are suitable for visualizing data within sequential processes, where data typically funnels through various stages.
 3. **Data Distribution**: When you want to gain insights into the distribution of data at each stage within a process, and you can represent multiple categories as stacked bars for comparative analysis.
 4. **Efficiency Assessment**: To assess the efficiency and effectiveness of a process, particularly when evaluating the attrition or conversion of elements at each stage.
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.funnel
+```

plugins/plotly-express/docs/histogram.md

@@ -10,3 +10,8 @@ Histogram plots are useful for:
 4. **Density Estimation**: Histograms can serve as the basis for density estimation methods, helping to model and understand underlying data distributions, which is crucial in statistical analysis and machine learning.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.histogram
+```

plugins/plotly-express/docs/icicle.md

@@ -10,3 +10,8 @@ Icicle plots are useful for:
 4. **Comparative Analysis**: The consistent and proportional layout of icicle charts makes them effective for comparing the size and structure of different branches within the hierarchy. Users can easily identify and compare the relative importance or size of various categories, facilitating better decision-making and resource allocation.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.icicle
+```

plugins/plotly-express/docs/index.rst

@@ -0,0 +1,6 @@
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

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

@@ -3,3 +3,9 @@
 To "layer" or "stack" multiple plots on top of each other, use the `layer` function. This is useful if you want to combine multiple plots of different types into a single plot, such as a scatter plot and a line plot. By default, last plot given will be used for the layout. The `which_layout` parameter can be used to specify which plot's layout should be used. The `specs` parameter can be used to specify the domains of each plot.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.layer
+```

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

@@ -12,3 +12,9 @@ Alternatives to 3D line plots include:
 
 - **Scatter Plots with Color or Size Mapping**: These can be used to represent three variables with the addition of color or size mapping to signify the third dimension.
 - **Surface Plots**: When visualizing continuous data over a 3D space, surface plots may be more appropriate, as they create a continuous surface representation.
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.line_3d
+```

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

@@ -10,3 +10,8 @@ Polar line plots are useful for:
 4. **Circular Data Exploration**: They can be used to explore and analyze data where the angular or periodic nature of the data is a significant aspect, making them useful in fields like meteorology, geophysics, and biology.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.line_polar
+```

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

@@ -7,3 +7,9 @@ Ternary line plots are useful for:
 1. **Compositional Data Representation**: Ternary line plots are suitable for representing compositional data where the total proportion remains constant, allowing for the visualization of how components change relative to one another.
 2. **Multivariate Data Analysis**: They are useful in multivariate data analysis to visualize relationships and trends among three variables or components that are interrelated.
 3. **Optimization Studies**: Ternary line plots can be applied in optimization studies to understand how adjustments in the proportions of three components impact the overall composition, aiding in informed decision-making.
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.line_ternary
+```

plugins/plotly-express/docs/line.md

@@ -395,3 +395,8 @@ scatter_plot_opacity = dx.scatter(
     opacity=0.5
 )
 ```
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.line
+```

plugins/plotly-express/docs/ohlc.md

@@ -11,3 +11,9 @@ OHLC (Open-High-Low-Close) plots are useful for:
 3. **Quantitative Analysis**: OHLC data can be leveraged for quantitative analysis, statistical modeling, and the development of trading strategies, making them valuable in algorithmic and systematic trading.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.ohlc
+```

plugins/plotly-express/docs/pie.md

@@ -13,3 +13,8 @@ Limitations of pie plots include:
 2. **Comparison Complexity**: Comparing the sizes of slices in a pie plot is less precise than with other chart types, such as bar plots or stacked bar charts. This makes it less suitable for situations where accurate quantitative comparisons are crucial.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.pie
+```

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

@@ -131,3 +131,8 @@ scatter_plot_color_column = dx.scatter_3d(
     color_discrete_map="identity"
 )
 ```
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.scatter_3d
+```

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

@@ -9,3 +9,9 @@ Polar scatter plots are useful for:
 3. **Angular or Periodic Data Relationships**: Polar scatter plots aid in exploring relationships and correlations in data with angular or periodic dependencies, making them suitable for applications where understanding circular patterns is essential.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.scatter_polar
+```

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

@@ -9,3 +9,9 @@ Ternary scatter plots are useful for:
 3. **Optimization Studies**: Ternary scatter plots aid in optimization studies to understand how adjustments in the proportions of three components impact the overall composition, making them valuable in informed decision-making processes.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.scatter_ternary
+```

plugins/plotly-express/docs/scatter.md

@@ -442,3 +442,8 @@ scatter_plot_opacity = dx.scatter(
     opacity=0.5
 )
 ```
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.scatter
+```

plugins/plotly-express/docs/strip.md

@@ -10,3 +10,9 @@ Strip plots are useful for:
 4. **Comparing Data Categories**: Comparing the distribution and spread of data across different categories or groups, making it useful for categorical data analysis.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.strip
+```

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

@@ -3,3 +3,9 @@
 Multiple sub plots can be combined into one plot using the `make_subplots` function. This function accepts multiple plot objects, and returns a single plot object. The plot objects can be any of the plot types supported by Deephaven Express. They can be arranged in a grid, or in a single row or column. The `shared_xaxes` and `shared_yaxes` parameters can be used to share axes between plots.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.make_subplots
+```

plugins/plotly-express/docs/sunburst.md

@@ -9,3 +9,8 @@ Sunburst plots are useful for:
 3. **Drill-Down Data Exploration**: Developers can implement sunburst plots for drill-down data exploration, allowing users to interactively explore and delve deeper into hierarchical data by clicking on sectors to reveal lower-level categories or information. This use case is valuable in applications that require detailed hierarchical data analysis.
 
 ## Examples
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.sunburst
+```

plugins/plotly-express/docs/timeline.md

@@ -3,3 +3,9 @@
 Timeline plots in offer a means to visualize time-related data, displaying events, durations, or activities along a time axis. Developers can utilize these plots for applications that require users to understand temporal patterns and relationships, such as project management, event scheduling, and historical data analysis.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.timeline
+```

plugins/plotly-express/docs/treemap.md

@@ -9,3 +9,9 @@ Treemap plots are useful for:
 3. **Data Summarization**: Treemaps are effective for summarizing large amounts of hierarchical data into a compact, visual format. Developers can use treemaps to provide users with an overview of hierarchical data, and users can drill down into specific categories for more detailed information.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.treemap
+```

plugins/plotly-express/docs/violin.md

@@ -10,3 +10,9 @@ Violin plots are useful for:
 4. **Multimodal Data**: They are particularly useful when dealing with data that exhibits multiple modes or peaks, as they can reveal these underlying patterns effectively.
 
 ## Examples
+
+
+## API Reference
+```{eval-rst}
+.. autofunction:: deephaven.plot.express.violin
+```

plugins/plotly-express/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=docs
+set BUILDDIR=docs/build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd