From caadb90fab4c6f20e32f1127dc1e161f1b09fc95 Mon Sep 17 00:00:00 2001 From: cosmicBboy Date: Sat, 21 Sep 2024 11:33:24 -0400 Subject: [PATCH 1/4] [wip] add docsearch Signed-off-by: cosmicBboy --- docs/source/conf.py | 13 ++++++------- docs/source/reference/dtypes.rst | 2 +- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index bbcfb4fd3..55635fde8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,7 +50,7 @@ "sphinx.ext.linkcode", # link to github, see linkcode_resolve() below "sphinx_copybutton", "sphinx_design", - # "sphinx_docsearch", + "sphinx_docsearch", "myst_nb", ] @@ -312,16 +312,15 @@ def linkcode_resolve(domain, info): ] myst_heading_anchors = 3 -myst_heading_anchors = 3 - nb_execution_mode = "auto" nb_execution_timeout = 60 nb_execution_excludepatterns = ["_contents/try_pandera.ipynb"] -# # docsearch configuration -# docsearch_app_id = "GA9NROLUXR" -# docsearch_api_key = os.getenv("DOCSEARCH_SEARCH_API_KEY") -# docsearch_index_name = "pandera" +# docsearch configuration +docsearch_app_id = "GA9NROLUXR" +docsearch_api_key = os.getenv("DOCSEARCH_SEARCH_API_KEY") +docsearch_index_name = "pandera" +docsearch_search_parameter = '{filters: ["version:latest"]}' class CustomWarningSuppressor(pylogging.Filter): diff --git a/docs/source/reference/dtypes.rst b/docs/source/reference/dtypes.rst index a1218997e..e888083ee 100644 --- a/docs/source/reference/dtypes.rst +++ b/docs/source/reference/dtypes.rst @@ -133,7 +133,7 @@ GeoPandas Dtypes :template: dtype.rst :nosignatures: - pandera.engines.pandas_engine.Geometry + pandera.engines.geopandas_engine.Geometry Pydantic Dtypes --------------- From 219ca11c08d1d4c64587949ad10e1c70982e1a49 Mon Sep 17 00:00:00 2001 From: cosmicBboy Date: Sun, 22 Sep 2024 16:20:30 -0400 Subject: [PATCH 2/4] add custom docsearch to conf.py Signed-off-by: cosmicBboy --- Makefile | 3 +- docs/source/_static/custom.js | 43 +++++++++++++ docs/source/_static/default.css | 29 ++++++--- docs/source/_static/docsearch_config.js_t | 13 ++++ docs/source/_templates/sidebar/search.html | 1 + docs/source/conf.py | 70 ++++++++++++++++++---- 6 files changed, 139 insertions(+), 20 deletions(-) create mode 100644 docs/source/_static/docsearch_config.js_t create mode 100644 docs/source/_templates/sidebar/search.html diff --git a/Makefile b/Makefile index bfdaf9ce5..1e907e898 100644 --- a/Makefile +++ b/Makefile @@ -27,8 +27,7 @@ docs: docs-clean python -m sphinx -W -E "docs/source" "docs/_build" && make -C docs doctest quick-docs: - python -m sphinx -E "docs/source" "docs/_build" -W && \ - make -C docs doctest + python -m sphinx -E "docs/source" "docs/_build" && make -C docs doctest code-cov: pytest --cov-report=html --cov=pandera tests/ diff --git a/docs/source/_static/custom.js b/docs/source/_static/custom.js index 388fda4e2..e500b8d23 100644 --- a/docs/source/_static/custom.js +++ b/docs/source/_static/custom.js @@ -9,3 +9,46 @@ window.addEventListener("DOMContentLoaded", function() { link.setAttribute("target", "_blank"); }); }); + + +function setHtmlDataTheme() { + // Set theme at the root html element + setTimeout(() => { + const theme = document.body.dataset.theme; + const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches; + + if (theme === "auto") { + document.documentElement.dataset.theme = prefersDark ? "dark" : "light"; + } else { + document.documentElement.dataset.theme = theme; + } + }, 10) + } + +function setupAlgoliaTheme() { + // To get darkmode in the algolia search modal, we need to set the theme in + // the root html element. This function propagates the theme set by furo + // that's set in the body element. + const buttons = document.getElementsByClassName("theme-toggle"); + + // set for initial document load + setHtmlDataTheme(); + + // listen for when theme button is clicked. + Array.from(buttons).forEach((btn) => { + btn.addEventListener("click", setHtmlDataTheme); + }); +} + +function main() { + setupAlgoliaTheme() +} + +document.addEventListener('DOMContentLoaded', main); +window.addEventListener('keydown', (event) => { + if (event.code === "Escape") { + // make sure to prevent default behavior with escape key so that algolia + // modal can be closed properly. + event.preventDefault(); + } +}); diff --git a/docs/source/_static/default.css b/docs/source/_static/default.css index 115b6139b..f87f1d0ce 100644 --- a/docs/source/_static/default.css +++ b/docs/source/_static/default.css @@ -153,14 +153,27 @@ div.DocSearch-Logo .cls-2 { .DocSearch-Button { height: 50px; + margin: 0; + width: 100%; + border-radius: 0; + border-bottom: 1px solid var(--color-header-border) !important; + border-top: 1px solid var(--color-header-border) !important; + background: var(--color-sidebar-background) !important; + padding: 0 15px !important; } -@media (prefers-color-scheme: dark) { - body:not([data-theme="light"]) .DocSearch-Button:active, - body:not([data-theme="light"]) .DocSearch-Button:focus, - body:not([data-theme="light"]) .DocSearch-Button:hover, - body:not([data-theme="light"]) .DocSearch-Button .DocSearch-Search-Icon { - background: #666; - color: rgb(245, 246, 247); - } +.DocSearch-Button:hover, .DocSearch-Button:active { + box-shadow: none !important; + background: var(--docsearch-searchbox-background) !important; +} + +.DocSearch-Button-Key, .DocSearch-Commands-Key { + border: none !important; + box-shadow: none !important; + display: inherit !important; + padding: 0 !important; +} + +.sidebar-search-container::before { + content: none; } diff --git a/docs/source/_static/docsearch_config.js_t b/docs/source/_static/docsearch_config.js_t new file mode 100644 index 000000000..5e11be10f --- /dev/null +++ b/docs/source/_static/docsearch_config.js_t @@ -0,0 +1,13 @@ +docsearch({ + container: "{{ docsearch_container|default('#docsearch') }}", + appId: "{{ docsearch_app_id }}", + apiKey: "{{ docsearch_api_key }}", + indexName: "{{ docsearch_index_name }}", + {%- if docsearch_search_parameters %} + searchParameters: { + {% for key, value in docsearch_search_parameters.items() %} + {{ key }}: {% if value is string %}"{{ value }}"{% else %}{{ value }}{% endif %}{% if not loop.last %},{% endif %} + {% endfor %} + } + {%- endif %} +}); diff --git a/docs/source/_templates/sidebar/search.html b/docs/source/_templates/sidebar/search.html new file mode 100644 index 000000000..c96b8f26c --- /dev/null +++ b/docs/source/_templates/sidebar/search.html @@ -0,0 +1 @@ +
diff --git a/docs/source/conf.py b/docs/source/conf.py index 55635fde8..48e9f5b5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,7 +50,6 @@ "sphinx.ext.linkcode", # link to github, see linkcode_resolve() below "sphinx_copybutton", "sphinx_design", - "sphinx_docsearch", "myst_nb", ] @@ -167,10 +166,15 @@ html_static_path = ["_static"] html_css_files = [ - "default.css", "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css", + "https://cdn.jsdelivr.net/npm/@docsearch/css@3", + "default.css", +] +html_js_files = [ + "custom.js", + "https://cdn.jsdelivr.net/npm/@docsearch/js@3", + "docsearch_config.js", ] -html_js_files = ["custom.js"] autosummary_generate = True autosummary_generate_overwrite = False @@ -312,15 +316,18 @@ def linkcode_resolve(domain, info): ] myst_heading_anchors = 3 -nb_execution_mode = "auto" +nb_execution_mode = "off" nb_execution_timeout = 60 nb_execution_excludepatterns = ["_contents/try_pandera.ipynb"] # docsearch configuration -docsearch_app_id = "GA9NROLUXR" +docsearch_container = "#docsearch" +docsearch_app_id = os.getenv("DOCSEARCH_SEARCH_APP_ID", "GA9NROLUXR") docsearch_api_key = os.getenv("DOCSEARCH_SEARCH_API_KEY") -docsearch_index_name = "pandera" -docsearch_search_parameter = '{filters: ["version:latest"]}' +docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME", "pandera") +docsearch_search_parameters = { + "facetFilters": [f"version:{os.getenv('$READTHEDOCS_VERSION', 'stable')}"] +} class CustomWarningSuppressor(pylogging.Filter): @@ -355,13 +362,56 @@ def filter(self, record: pylogging.LogRecord) -> bool: return True -def setup(app: sphinx.application.Sphinx) -> None: - """Setup root logger for Sphinx""" +def add_warning_suppressor(app: sphinx.application.Sphinx) -> None: logger = pylogging.getLogger("sphinx") - warning_handler, *_ = [ h for h in logger.handlers if isinstance(h, logging.WarningStreamHandler) ] warning_handler.filters.insert(0, CustomWarningSuppressor(app)) + + +def add_docsearch_config(app: sphinx.application.Sphinx) -> None: + app.add_config_value( + "docsearch_app_id", default="", rebuild="html", types=[str] + ) + app.add_config_value( + "docsearch_api_key", default="", rebuild="html", types=[str] + ) + app.add_config_value( + "docsearch_index_name", default="", rebuild="html", types=[str] + ) + app.add_config_value( + "docsearch_container", + default="#docsearch", + rebuild="html", + types=[str], + ) + app.add_config_value( + "docsearch_search_parameters", default="", rebuild="html", types=[dict] + ) + + +def add_docsearch_assets( + app: sphinx.application.Sphinx, config: sphinx.application.Config +): + app.add_js_file("docsearch_config.js", loading_method="defer") + + # Update global context + config.html_context.update( + { + "docsearch_app_id": config.docsearch_app_id, + "docsearch_api_key": app.config.docsearch_api_key, + "docsearch_index_name": app.config.docsearch_index_name, + "docsearch_container": app.config.docsearch_container, + "docsearch_search_parameters": app.config.docsearch_search_parameters, + } + ) + + +def setup(app: sphinx.application.Sphinx) -> None: + add_warning_suppressor(app) + add_docsearch_config(app) + + app.connect("config-inited", add_docsearch_assets) From f16a2f8224f5f8cf6749702888baedede356469d Mon Sep 17 00:00:00 2001 From: cosmicBboy Date: Sun, 22 Sep 2024 18:42:30 -0400 Subject: [PATCH 3/4] enable nb execution mode Signed-off-by: cosmicBboy --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 48e9f5b5c..85eef9f14 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -316,7 +316,7 @@ def linkcode_resolve(domain, info): ] myst_heading_anchors = 3 -nb_execution_mode = "off" +nb_execution_mode = os.getenv("PANDERA_DOCS_NB_EXECUTION_MODE", "auto") nb_execution_timeout = 60 nb_execution_excludepatterns = ["_contents/try_pandera.ipynb"] From 7164b3c009dee5d841852fb1b77fa9fc47e7e0d6 Mon Sep 17 00:00:00 2001 From: cosmicBboy Date: Sun, 22 Sep 2024 22:48:34 -0400 Subject: [PATCH 4/4] fix env var name Signed-off-by: cosmicBboy --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 85eef9f14..501c98076 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -326,7 +326,7 @@ def linkcode_resolve(domain, info): docsearch_api_key = os.getenv("DOCSEARCH_SEARCH_API_KEY") docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME", "pandera") docsearch_search_parameters = { - "facetFilters": [f"version:{os.getenv('$READTHEDOCS_VERSION', 'stable')}"] + "facetFilters": [f"version:{os.getenv('READTHEDOCS_VERSION', 'stable')}"] }