Merge branch 'main' into 88-plotly-in-sphinx

Author: tpvasconcelos

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.2.1
+current_version = 0.3.0
 commit = True
 commit_args = -s
 message = Release version {new_version}

.gitignore

@@ -2,6 +2,8 @@
 #  Project specific
 # ============================================================================
 
+docs/api/autogen
+docs/api/public
 docs/examples_gallery_out/
 docs/sg_execution_times.rst
 

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: check-ast
       - id: check-executables-have-shebangs
       - id: check-json
+        exclude: ^pyrightconfig\.json$
       - id: check-merge-conflict
       - id: check-shebang-scripts-are-executable
       - id: check-symlinks
@@ -33,7 +34,7 @@ repos:
       - id: pretty-format-json
         args: [ --autofix, --no-sort-keys ]
         # ignore jupyter notebooks
-        exclude: ^.*\.ipynb$
+        exclude: (^.*\.ipynb$|^pyrightconfig\.json$)
       - id: pretty-format-json
         args: [ --autofix, --no-sort-keys, --indent=1, --no-ensure-ascii ]
         # only jupyter notebooks
@@ -101,7 +102,7 @@ repos:
         additional_dependencies: [setuptools-scm]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.1
+    rev: v0.8.3
     hooks:
       - id: ruff-format
       - id: ruff

MANIFEST.in

@@ -30,6 +30,8 @@ recursive-include docs/_templates *.html
 exclude docs/sg_execution_times.rst
 prune docs/examples_gallery_out
 prune docs/build
+prune docs/api/autogen
+prune docs/api/public
 
 # Misc
 recursive-include .github *.yml *.yaml

cicd_utils/cicd/compile_plotly_charts.py

@@ -10,14 +10,16 @@
 
 from copy import deepcopy
 from pathlib import Path
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING
 
 from minify_html import minify
 from plotly.offline import get_plotlyjs
 
 from ridgeplot_examples import ALL_EXAMPLES, tighten_margins
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     import plotly.graph_objects as go
 
 

cicd_utils/ridgeplot_examples/__init__.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from typing import Callable
+from typing import TYPE_CHECKING
 
 import plotly.graph_objects as go
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 
 def tighten_margins(fig: go.Figure, px: int = 0) -> go.Figure:
     """Tighten the margins of a Plotly figure."""

docs/api/index.rst

@@ -19,13 +19,3 @@ Data loading utilities
 
    ridgeplot.datasets.load_probly
    ridgeplot.datasets.load_lincoln_weather
-
-
-Internals
-=========
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   internal/*

docs/api/internal/_color/colorscale.rst

@@ -10,7 +10,7 @@
 try:
     import importlib.metadata as importlib_metadata
 except ImportError:
-    import importlib_metadata  # pyright: ignore[no-redef]
+    import importlib_metadata
 
 try:
     from cicd.compile_plotly_charts import compile_plotly_charts
@@ -56,8 +56,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/intro.html
     "myst_parser",
-    "notfound.extension",
+    # https://www.sphinx-doc.org/en/master/usage/extensions/index.html
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
@@ -79,10 +80,16 @@
     "sphinx_sitemap",
     "sphinx_thebe",
     "sphinx_togglebutton",
+    # https://github.com/sphinx-contrib/apidoc
+    "sphinxcontrib.apidoc",
+    # https://github.com/sphinx-toolbox/sphinx-toolbox
     "sphinx_toolbox.collapse",
     "sphinx_toolbox.more_autodoc.autoprotocol",
     "sphinx_toolbox.more_autodoc.generic_bases",
+    # https://github.com/wpilibsuite/sphinxext-opengraph
     "sphinxext.opengraph",
+    # https://github.com/readthedocs/sphinx-notfound-page
+    "notfound.extension",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -207,6 +214,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "packaging": ("https://packaging.pypa.io/en/latest", None),
+    "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
@@ -220,7 +228,14 @@
 sitemap_url_scheme = "{link}"
 
 
-# -- autodoc, napoleon, and autodoc-typehints ------------------------------------------------------
+# -- autodoc, apidoc, napoleon, and autodoc-typehints ----------------------------------------------
+
+# apidoc config
+apidoc_module_dir = "../src/ridgeplot"
+apidoc_output_dir = "api/autogen"
+apidoc_separate_modules = True
+apidoc_extra_args = ["--no-toc", "--private"]
+
 
 # autosectionlabel
 autosectionlabel_prefix_document = True
@@ -254,7 +269,7 @@
 napoleon_use_admonition_for_examples = True
 napoleon_use_admonition_for_notes = False
 napoleon_use_param = False
-# napoleon_use_rtype = False
+napoleon_use_rtype = True
 napoleon_preprocess_types = True
 napoleon_attr_annotations = True
 
@@ -379,19 +394,7 @@ def reset_sys_argv() -> Generator[None]:
         sys.argv = original_sys_argv
 
 
-def _fix_generated_public_api_rst() -> None:
-    from pre_commit_hooks.end_of_file_fixer import main as end_of_file_fixer
-    from pre_commit_hooks.fix_byte_order_marker import main as fix_byte_order_marker
-
-    files = [file.resolve().as_posix() for file in Path("api/public/").glob("*.rst")]
-    if not files:
-        raise RuntimeError("No RST files found. Check that the path above is correct.")
-    with reset_sys_argv():
-        end_of_file_fixer(files)
-        fix_byte_order_marker(files)
-
-
-def _fix_html_charts() -> None:
+def _fix_html_charts(app: Sphinx, exception: Exception | None) -> None:
     from pre_commit_hooks.end_of_file_fixer import main as end_of_file_fixer
 
     files = [file.resolve().as_posix() for file in Path("_static/charts/").glob("*.html")]
@@ -401,7 +404,7 @@ def _fix_html_charts() -> None:
         end_of_file_fixer(files)
 
 
-def rename_plotly_io_show() -> None:
+def _rename_plotly_io_show(app: Sphinx) -> None:
     """Rename usages of `plotly.io.show` to `fig.show`."""
     from pathlib import Path
 
@@ -420,6 +423,5 @@ def setup(app: Sphinx) -> None:
     compile_plotly_charts()
     # app.connect("html-page-context", register_jinja_functions)
 
-    app.connect("builder-inited", lambda *_: rename_plotly_io_show())  # pyright: ignore[reportUnknownLambdaType]
-    app.connect("build-finished", lambda *_: _fix_generated_public_api_rst())  # pyright: ignore[reportUnknownLambdaType]
-    app.connect("build-finished", lambda *_: _fix_html_charts())  # pyright: ignore[reportUnknownLambdaType]
+    app.connect("builder-inited", _rename_plotly_io_show)
+    app.connect("build-finished", _fix_html_charts)

docs/api/internal/_color/css_colors.rst

@@ -5,6 +5,16 @@ This document outlines the list of changes to ridgeplot between each release. Fo
 Unreleased changes
 ------------------
 
+### Internal
+
+- Improve type annotations and use stricter pyright settings ({gh-pr}`291`)
+- Use `sphinxcontrib.apidoc` to automatically generate API docs from the source code ({gh-pr}`296`)
+
+---
+
+0.3.0
+------
+
 ### Features
 
 - Add support for histogram and bar traces ({gh-pr}`287`)

docs/api/internal/_color/interpolation.rst

@@ -42,7 +42,7 @@ dependencies = [
     "numpy>=1",
     "plotly>=5.20",  # The `fillgradient` option was added in 5.20
     "statsmodels>=0.12,!=0.14.2",  # See GH197 for details
-    'typing-extensions; python_version<"3.13"',
+    "typing-extensions",
     'importlib-resources; python_version<"3.10"',
 ]