Update apidoc for Sphinx 7. Relates to #4085

doc/apidoc/Makefile

@@ -29,7 +29,7 @@ help:
 	# docstrings. The first path is the one to process, the following ones
 	# are excluded from the search.
 	rm -rf _build generated
-	sphinx-apidoc -M -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
+	sphinx-apidoc -M -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api ../../packages/python/plotly/plotly/plotly
 	# Run sphinx-build to build html pages from the rst pages
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	git checkout -- ../../packages/python/plotly/plotly/graph_objs
@@ -42,4 +42,4 @@ help:
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.inv
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.js
 	sed -i 's/graph_objs/graph_objects/g' _build/html/generated/*.html
-	sed -i 's/graph_objs/graph_objects/g' _build/html/generated/generated/*.html
+	# sed -i 's/graph_objs/graph_objects/g' _build/html/generated/generated/*.html

doc/apidoc/_static/plotly-style.css

@@ -27,7 +27,7 @@
   padding-top: 8px;
 }
 
-code {
+.rst-content code.literal {
   color: #2c3e50 !important;
 }
 
@@ -97,10 +97,41 @@ h6 {
   font-weight: 500;
 }
 
+.wy-nav-side {
+  background-color: #0e1012;
+}
+
+.wy-side-nav-search {
+  background-color: #0e1012 !important;
+}
+
+/*
+
 a {
   color: #506784 !important;
 }
 
 a:hover {
   color: #0d67bf !important;
 }
+
+*/
+
+a.icon img.logo {
+  margin-top: 0 !important ;
+}
+
+.wy-side-nav-search .wy-dropdown > a img.logo, .wy-side-nav-search > a img.logo {
+  width: 275px;
+}
+
+.wy-table-responsive table td {
+  white-space: normal;
+}
+
+/* https://github.com/readthedocs/sphinx_rtd_theme/issues/468 */
+/* adds scrollbar to sidenav */
+.wy-side-scroll {
+  width: auto;
+  overflow-y: auto;
+}

doc/apidoc/_templates/class_figure.rst

@@ -1,12 +1,10 @@
 :mod:`{{module}}`.{{objname}}
-{{ underline }}==============
+{{ underline }}=========================================================
 
 
 .. currentmodule:: {{ module }}
 
 .. autosummary::
-   :toctree: generated/
-
    Figure
 
    Figure.show

doc/apidoc/conf.py

@@ -12,15 +12,11 @@
 #
 import os
 import sys
-import sphinx_bootstrap_theme
-
-# sys.path.insert(0, os.path.abspath("../packages/python/plotly"))
-
 
 # -- Project information -----------------------------------------------------
 
 project = ""
-copyright = "2022, Plotly"
+copyright = "2024, Plotly"
 author = "Plotly"
 
 # The short X.Y version
@@ -63,13 +59,6 @@
 # The master toctree document.
 master_doc = "index"
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -85,18 +74,21 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "bootstrap"
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
-html_logo = "_static/logo.png"
+html_theme = "sphinx_rtd_theme"
+html_logo = "_static/graphing_library.svg"
+html_show_sourcelink = False
+
+# -- If dark mode option wanted. Needs pip install sphinx-rtd-dark-mode
+# extensions.append("sphinx_rtd_dark_mode")
+# default_dark_mode = False
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
-    "analytics_id": "UA-39373211-1",  # not supported by this theme
-    "bootswatch_theme": "flatly",
-    "source_link_position": "no",
+    "analytics_id": "UA-39373211-1",  # supported by rtd theme. Not by bootstrap?
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -111,9 +103,14 @@
 # defined by theme itself.  Builtin themes are using these templates by
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
-#
 # html_sidebars = {}
 
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
+# This doesn't seem to get us anywhere
+# html_sidebars = {
+#   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
+# }
+
 html_favicon = "_static/favicon.ico"
 
 # -- Options for HTMLHelp output ---------------------------------------------
@@ -171,7 +168,6 @@
     )
 ]
 
-
 # -- Options for Epub output -------------------------------------------------
 
 # Bibliographic Dublin Core info.
@@ -202,6 +198,8 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-
-def setup(app):
-    app.add_stylesheet("plotly-style.css")  # also can be a full URL
+# Adding the bootstrap theme makes little difference - rules in the RTD theme are usually more specific
+html_css_files = [
+    # "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css",
+    "plotly-style.css"
+]

doc/apidoc/requirements.txt

@@ -0,0 +1,7 @@
+# Any version of pandas, it just allows plotly express to be imported
+pandas
+black
+sphinx==7.3.7
+sphinx-rtd-theme==2.0.0
+tenacity
+# Do not include plotly here, get it from code