From 4ecc59efbb4b3766f8162708e5914a7419fdda11 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 30 May 2024 13:37:16 +0100 Subject: [PATCH] Update apidoc for Sphinx 7. Relates to #4085 --- doc/apidoc/Makefile | 4 +-- doc/apidoc/_static/graphing_library.svg | 1 + doc/apidoc/_static/plotly-style.css | 33 ++++++++++++++++++- doc/apidoc/_templates/class_figure.rst | 4 +-- doc/apidoc/conf.py | 44 ++++++++++++------------- doc/apidoc/requirements.txt | 7 ++++ 6 files changed, 64 insertions(+), 29 deletions(-) create mode 100755 doc/apidoc/_static/graphing_library.svg create mode 100755 doc/apidoc/requirements.txt diff --git a/doc/apidoc/Makefile b/doc/apidoc/Makefile index 06e5fba7bb3..554bd256c8c 100644 --- a/doc/apidoc/Makefile +++ b/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 diff --git a/doc/apidoc/_static/graphing_library.svg b/doc/apidoc/_static/graphing_library.svg new file mode 100755 index 00000000000..3a7a8256428 --- /dev/null +++ b/doc/apidoc/_static/graphing_library.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/apidoc/_static/plotly-style.css b/doc/apidoc/_static/plotly-style.css index a5b9433487c..1a147c2d2ba 100644 --- a/doc/apidoc/_static/plotly-style.css +++ b/doc/apidoc/_static/plotly-style.css @@ -27,7 +27,7 @@ padding-top: 8px; } -code { +.rst-content code.literal { color: #2c3e50 !important; } @@ -97,6 +97,16 @@ h6 { font-weight: 500; } +.wy-nav-side { + background-color: #0e1012; +} + +.wy-side-nav-search { + background-color: #0e1012 !important; +} + +/* + a { color: #506784 !important; } @@ -104,3 +114,24 @@ a { 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; +} \ No newline at end of file diff --git a/doc/apidoc/_templates/class_figure.rst b/doc/apidoc/_templates/class_figure.rst index 9c5fc37f8f5..0a26601c07d 100644 --- a/doc/apidoc/_templates/class_figure.rst +++ b/doc/apidoc/_templates/class_figure.rst @@ -1,12 +1,10 @@ :mod:`{{module}}`.{{objname}} -{{ underline }}============== +{{ underline }}========================================================= .. currentmodule:: {{ module }} .. autosummary:: - :toctree: generated/ - Figure Figure.show diff --git a/doc/apidoc/conf.py b/doc/apidoc/conf.py index 9ffb4e9b271..4d984f4c0f1 100644 --- a/doc/apidoc/conf.py +++ b/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/bootstrap@4.4.1/dist/css/bootstrap.min.css", + "plotly-style.css" +] diff --git a/doc/apidoc/requirements.txt b/doc/apidoc/requirements.txt new file mode 100755 index 00000000000..a45d593649b --- /dev/null +++ b/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 \ No newline at end of file