From a93d0301162d6ea77a68a762ce502bbb0806de63 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Wed, 27 Apr 2022 12:42:33 -0700 Subject: [PATCH 01/14] rework doc index page in light of new xarray.dev splash page --- doc/_static/index_api.svg | 97 +++++++++++++++++ doc/_static/index_contribute.svg | 76 +++++++++++++ doc/_static/index_getting_started.svg | 66 ++++++++++++ doc/_static/index_user_guide.svg | 67 ++++++++++++ doc/_static/style.css | 44 ++++++++ doc/conf.py | 5 + doc/index.rst | 147 ++++++++++++++------------ 7 files changed, 434 insertions(+), 68 deletions(-) create mode 100644 doc/_static/index_api.svg create mode 100644 doc/_static/index_contribute.svg create mode 100644 doc/_static/index_getting_started.svg create mode 100644 doc/_static/index_user_guide.svg diff --git a/doc/_static/index_api.svg b/doc/_static/index_api.svg new file mode 100644 index 00000000000..87013d24ce3 --- /dev/null +++ b/doc/_static/index_api.svg @@ -0,0 +1,97 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/doc/_static/index_contribute.svg b/doc/_static/index_contribute.svg new file mode 100644 index 00000000000..399f1d7630b --- /dev/null +++ b/doc/_static/index_contribute.svg @@ -0,0 +1,76 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/doc/_static/index_getting_started.svg b/doc/_static/index_getting_started.svg new file mode 100644 index 00000000000..d1c7b08a2a1 --- /dev/null +++ b/doc/_static/index_getting_started.svg @@ -0,0 +1,66 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/_static/index_user_guide.svg b/doc/_static/index_user_guide.svg new file mode 100644 index 00000000000..bff2482423d --- /dev/null +++ b/doc/_static/index_user_guide.svg @@ -0,0 +1,67 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/_static/style.css b/doc/_static/style.css index 833b11a83ab..1ca4dca6027 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -261,3 +261,47 @@ body { .bd-toc .nav > .active > ul { display: block; } + +/* Main index page overview cards */ + +.intro-card { + background: #fff; + border-radius: 0; + padding: 30px 10px 20px 10px; + margin: 10px 0px; +} + +.intro-card p.card-text { + margin: 0px; +} + +.intro-card .card-img-top { + margin: 10px; + height: 52px; +} + +.intro-card .card-header { + border: none; + background-color:white; + color: #5a5a5a !important; + font-size: var(--pst-font-size-h5); + font-weight: bold; + padding: 2.5rem 0rem 0.5rem 0rem; +} + +.intro-card .card-footer { + border: none; + background-color:white; +} + +.intro-card .card-footer p.card-text{ + max-width: 220px; + margin-left: auto; + margin-right: auto; +} + +.btn-secondary { + color: #fff !important; + background-color: #6c757d; + border-color: #6c757d; +} diff --git a/doc/conf.py b/doc/conf.py index 8ce9efdce88..d271e8fe9e3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -60,6 +60,8 @@ ] ) +nbsphinx_allow_errors = True + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -84,7 +86,10 @@ "sphinxext.opengraph", "sphinx_copybutton", "sphinxext.rediraffe", + 'sphinx_panels' ] +panels_add_bootstrap_css = False + extlinks = { "issue": ("https://github.com/pydata/xarray/issues/%s", "GH"), diff --git a/doc/index.rst b/doc/index.rst index c549c33aa62..c0e472cf708 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,26 +1,87 @@ -xarray: N-D labeled arrays and datasets in Python -================================================= +Xarray documentation +==================== -**xarray** (formerly **xray**) is an open source project and Python package -that makes working with labelled multi-dimensional arrays simple, +Xarray makes working with labelled multi-dimensional arrays in Python simple, efficient, and fun! -Xarray introduces labels in the form of dimensions, coordinates and -attributes on top of raw NumPy_-like arrays, which allows for a more -intuitive, more concise, and less error-prone developer experience. -The package includes a large and growing library of domain-agnostic functions -for advanced analytics and visualization with these data structures. +**Useful links**: +`Home `__ | +`Code Repository `__ | +`Issues `__ | +`Discussions `__ | +`Releases `__ | +`Stack Overflow `__ | +`Mailing List `__ -Xarray is inspired by and borrows heavily from pandas_, the popular data -analysis package focused on labelled tabular data. -It is particularly tailored to working with netCDF_ files, which were the -source of xarray's data model, and integrates tightly with dask_ for parallel -computing. +.. panels:: + :card: + intro-card text-center + :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex -.. _NumPy: https://www.numpy.org -.. _pandas: https://pandas.pydata.org -.. _dask: https://dask.org -.. _netCDF: https://www.unidata.ucar.edu/software/netcdf + --- + :img-top: _static/index_getting_started.svg + + Getting started + ^^^^^^^^^^^^^^^ + + New to *xarray*? Check out the getting started guides. They contain an + introduction to *Xarray's* main concepts and links to additional tutorials. + + +++ + + .. link-button:: getting-started-guide/index + :type: ref + :text: To the getting started guides + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_user_guide.svg + + User guide + ^^^^^^^^^^ + + The user guide provides in-depth information on the + key concepts of Xarray with useful background information and explanation. + + +++ + + .. link-button:: user-guide/index + :type: ref + :text: To the user guide + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_api.svg + + API reference + ^^^^^^^^^^^^^ + + The reference guide contains a detailed description of the Xarray API. + The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of the key concepts. + + +++ + + .. link-button:: api + :type: ref + :text: To the reference guide + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_contribute.svg + + Developer guide + ^^^^^^^^^^^^^^^ + + Saw a typo in the documentation? Want to improve existing functionalities? + The contributing guidelines will guide you through the process of improving + Xarray. + + +++ + + .. link-button:: contributing + :type: ref + :text: To the development guide + :classes: btn-block btn-secondary stretched-link .. toctree:: @@ -57,53 +118,3 @@ computing. GitHub discussions StackOverflow - - - -Get in touch ------------- - -- If you have a question like "How do I concatenate a list of datasets?", ask on `GitHub discussions`_ or `StackOverflow`_. - Please include a self-contained reproducible example if possible. -- Report bugs, suggest features or view the source code `on GitHub`_. -- For less well defined questions or ideas, or to announce other projects of - interest to xarray users, use `GitHub discussions`_ or the `mailing list`_. - -.. _StackOverFlow: https://stackoverflow.com/questions/tagged/python-xarray -.. _Github discussions: https://github.com/pydata/xarray/discussions -.. _mailing list: https://groups.google.com/forum/#!forum/xarray -.. _on GitHub: https://github.com/pydata/xarray - -NumFOCUS --------- - -.. image:: _static/numfocus_logo.png - :scale: 50 % - :target: https://numfocus.org/ - -Xarray is a fiscally sponsored project of NumFOCUS_, a nonprofit dedicated -to supporting the open source scientific computing community. If you like -Xarray and want to support our mission, please consider making a donation_ -to support our efforts. - -.. _donation: https://numfocus.salsalabs.org/donate-to-xarray/ - - -History -------- - -Xarray is an evolution of an internal tool developed at `The Climate -Corporation`__. It was originally written by Climate Corp researchers Stephan -Hoyer, Alex Kleeman and Eugene Brevdo and was released as open source in -May 2014. The project was renamed from "xray" in January 2016. Xarray became a -fiscally sponsored project of NumFOCUS_ in August 2018. - -__ https://climate.com/ -.. _NumFOCUS: https://numfocus.org - -License -------- - -Xarray is available under the open source `Apache License`__. - -__ https://www.apache.org/licenses/LICENSE-2.0.html From fac2ea0c1f6d07f3471dbc5793bad8bfc3dbe7f3 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Tue, 10 May 2022 09:40:02 -0600 Subject: [PATCH 02/14] Silence `WARNING: more than one target found for 'any' cross-reference` --- doc/conf.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 7aaf5692564..034e1f0983d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,6 +18,7 @@ import subprocess import sys from contextlib import suppress +from sphinx.domains.python import PythonDomain import sphinx_autosummary_accessors @@ -388,5 +389,19 @@ def html_page_context(app, pagename, templatename, context, doctree): context["theme_use_edit_page_button"] = False + +class PatchedPythonDomain(PythonDomain): + """ + Workaround for `WARNING: more than one target found for 'any' cross-reference` + + source: https://github.com/sphinx-doc/sphinx/issues/3866 + """ + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + if 'refspecific' in node: + del node['refspecific'] + return super(PatchedPythonDomain, self).resolve_xref( + env, fromdocname, builder, typ, target, node, contnode) + def setup(app): app.connect("html-page-context", html_page_context) + app.add_domain(PatchedPythonDomain, override=True) From 6b7523f538ee68e5f1e0675a48988d477864a6fa Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 10 May 2022 15:41:58 +0000 Subject: [PATCH 03/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/conf.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 034e1f0983d..87c4c6fa665 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,9 +18,9 @@ import subprocess import sys from contextlib import suppress -from sphinx.domains.python import PythonDomain import sphinx_autosummary_accessors +from sphinx.domains.python import PythonDomain import xarray @@ -389,18 +389,20 @@ def html_page_context(app, pagename, templatename, context, doctree): context["theme_use_edit_page_button"] = False - class PatchedPythonDomain(PythonDomain): """ Workaround for `WARNING: more than one target found for 'any' cross-reference` source: https://github.com/sphinx-doc/sphinx/issues/3866 """ + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): - if 'refspecific' in node: - del node['refspecific'] - return super(PatchedPythonDomain, self).resolve_xref( - env, fromdocname, builder, typ, target, node, contnode) + if "refspecific" in node: + del node["refspecific"] + return super().resolve_xref( + env, fromdocname, builder, typ, target, node, contnode + ) + def setup(app): app.connect("html-page-context", html_page_context) From a233ac6f099994fa63d9a455adc0b72c544d364a Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 14:39:09 -0400 Subject: [PATCH 04/14] move to sphinx-design --- ci/requirements/doc.yml | 2 +- doc/_static/style.css | 42 ++-------------- doc/conf.py | 3 +- doc/index.rst | 106 ++++++++++++++-------------------------- 4 files changed, 42 insertions(+), 111 deletions(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 4c4f5fe3025..437c493c92c 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -32,7 +32,7 @@ dependencies: - sphinx-autosummary-accessors - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - - sphinx-panels + - sphinx-design - sphinx!=4.4.0 - zarr>=2.4 - pip: diff --git a/doc/_static/style.css b/doc/_static/style.css index 1ca4dca6027..6f7538724cf 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -264,44 +264,10 @@ body { /* Main index page overview cards */ -.intro-card { - background: #fff; - border-radius: 0; - padding: 30px 10px 20px 10px; - margin: 10px 0px; -} - -.intro-card p.card-text { - margin: 0px; -} - -.intro-card .card-img-top { - margin: 10px; - height: 52px; -} - -.intro-card .card-header { - border: none; - background-color:white; - color: #5a5a5a !important; - font-size: var(--pst-font-size-h5); - font-weight: bold; - padding: 2.5rem 0rem 0.5rem 0rem; -} - -.intro-card .card-footer { - border: none; - background-color:white; -} - -.intro-card .card-footer p.card-text{ - max-width: 220px; +.sd-card-img-top { + width: 50% !important; + display: block; margin-left: auto; margin-right: auto; -} - -.btn-secondary { - color: #fff !important; - background-color: #6c757d; - border-color: #6c757d; + margin-top: 10px; } diff --git a/doc/conf.py b/doc/conf.py index 87c4c6fa665..deabf409bef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -87,9 +87,8 @@ "sphinxext.opengraph", "sphinx_copybutton", "sphinxext.rediraffe", - "sphinx_panels", + "sphinx_design", ] -panels_add_bootstrap_css = False extlinks = { diff --git a/doc/index.rst b/doc/index.rst index e10ecd13a83..49b1c407610 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,76 +13,42 @@ efficient, and fun! `Stack Overflow `__ | `Mailing List `__ -.. panels:: - :card: + intro-card text-center - :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex - - --- - :img-top: _static/index_getting_started.svg - - Getting started - ^^^^^^^^^^^^^^^ - - New to *xarray*? Check out the getting started guides. They contain an - introduction to *Xarray's* main concepts and links to additional tutorials. - - +++ - - .. link-button:: getting-started-guide/index - :type: ref - :text: To the getting started guides - :classes: btn-block btn-secondary stretched-link - - --- - :img-top: _static/index_user_guide.svg - - User guide - ^^^^^^^^^^ - - The user guide provides in-depth information on the - key concepts of Xarray with useful background information and explanation. - - +++ - - .. link-button:: user-guide/index - :type: ref - :text: To the user guide - :classes: btn-block btn-secondary stretched-link - - --- - :img-top: _static/index_api.svg - - API reference - ^^^^^^^^^^^^^ - - The reference guide contains a detailed description of the Xarray API. - The reference describes how the methods work and which parameters can - be used. It assumes that you have an understanding of the key concepts. - - +++ - - .. link-button:: api - :type: ref - :text: To the reference guide - :classes: btn-block btn-secondary stretched-link - - --- - :img-top: _static/index_contribute.svg - - Developer guide - ^^^^^^^^^^^^^^^ - - Saw a typo in the documentation? Want to improve existing functionalities? - The contributing guidelines will guide you through the process of improving - Xarray. - - +++ - - .. link-button:: contributing - :type: ref - :text: To the development guide - :classes: btn-block btn-secondary stretched-link - +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: Getting started + :img-top: _static/index_getting_started.svg + :link: getting-started-guide/index + :link-type: ref + + New to *xarray*? Check out the getting started guides. They contain an + introduction to *Xarray's* main concepts and links to additional tutorials. + + .. grid-item-card:: User guide + :img-top: _static/index_user_guide.svg + :link: user-guide/index + :link-type: ref + + The user guide provides in-depth information on the + key concepts of Xarray with useful background information and explanation. + + .. grid-item-card:: API reference + :img-top: _static/index_api.svg + :link: api + :link-type: ref + + The reference guide contains a detailed description of the Xarray API. + The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of the key concepts. + + .. grid-item-card:: Developer guide + :img-top: _static/index_contribute.svg + :link: contributing + :link-type: ref + + Saw a typo in the documentation? Want to improve existing functionalities? + The contributing guidelines will guide you through the process of improving + Xarray. .. toctree:: :maxdepth: 2 From c6f438b2c241179d765cfc822d54a25393031b1d Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 14:49:17 -0400 Subject: [PATCH 05/14] tweak cards --- doc/_static/style.css | 2 +- doc/index.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/_static/style.css b/doc/_static/style.css index 6f7538724cf..3c21d7ac7c9 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -265,7 +265,7 @@ body { /* Main index page overview cards */ .sd-card-img-top { - width: 50% !important; + width: 33% !important; display: block; margin-left: auto; margin-right: auto; diff --git a/doc/index.rst b/doc/index.rst index 49b1c407610..8e8cbf4df73 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,7 +19,7 @@ efficient, and fun! .. grid-item-card:: Getting started :img-top: _static/index_getting_started.svg :link: getting-started-guide/index - :link-type: ref + :link-type: doc New to *xarray*? Check out the getting started guides. They contain an introduction to *Xarray's* main concepts and links to additional tutorials. @@ -27,7 +27,7 @@ efficient, and fun! .. grid-item-card:: User guide :img-top: _static/index_user_guide.svg :link: user-guide/index - :link-type: ref + :link-type: doc The user guide provides in-depth information on the key concepts of Xarray with useful background information and explanation. @@ -35,7 +35,7 @@ efficient, and fun! .. grid-item-card:: API reference :img-top: _static/index_api.svg :link: api - :link-type: ref + :link-type: doc The reference guide contains a detailed description of the Xarray API. The reference describes how the methods work and which parameters can @@ -44,7 +44,7 @@ efficient, and fun! .. grid-item-card:: Developer guide :img-top: _static/index_contribute.svg :link: contributing - :link-type: ref + :link-type: doc Saw a typo in the documentation? Want to improve existing functionalities? The contributing guidelines will guide you through the process of improving From 6bf9ace3aea1868feee7e7e15a392ac5b3426898 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 15:01:45 -0400 Subject: [PATCH 06/14] cleanup conf --- doc/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index deabf409bef..86ae1f3490e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -83,7 +83,6 @@ "nbsphinx", "sphinx_autosummary_accessors", "sphinx.ext.linkcode", - "sphinx_panels", "sphinxext.opengraph", "sphinx_copybutton", "sphinxext.rediraffe", From dd4f1ae7882613038ccbdf96938d5a30300156eb Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 15:07:45 -0400 Subject: [PATCH 07/14] cleanup conf.py --- doc/conf.py | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 86ae1f3490e..06f76ee8509 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -20,7 +20,6 @@ from contextlib import suppress import sphinx_autosummary_accessors -from sphinx.domains.python import PythonDomain import xarray @@ -387,21 +386,5 @@ def html_page_context(app, pagename, templatename, context, doctree): context["theme_use_edit_page_button"] = False -class PatchedPythonDomain(PythonDomain): - """ - Workaround for `WARNING: more than one target found for 'any' cross-reference` - - source: https://github.com/sphinx-doc/sphinx/issues/3866 - """ - - def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): - if "refspecific" in node: - del node["refspecific"] - return super().resolve_xref( - env, fromdocname, builder, typ, target, node, contnode - ) - - def setup(app): app.connect("html-page-context", html_page_context) - app.add_domain(PatchedPythonDomain, override=True) From 7635bdb5318a5e091b11ed5ef1aba9368b092ce3 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 15:38:36 -0400 Subject: [PATCH 08/14] add panels back --- ci/requirements/doc.yml | 1 + doc/conf.py | 1 + 2 files changed, 2 insertions(+) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 437c493c92c..6ca43fe78be 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -33,6 +33,7 @@ dependencies: - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - sphinx-design + - sphinx_panels - sphinx!=4.4.0 - zarr>=2.4 - pip: diff --git a/doc/conf.py b/doc/conf.py index 06f76ee8509..3e8cc2dbd10 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -85,6 +85,7 @@ "sphinxext.opengraph", "sphinx_copybutton", "sphinxext.rediraffe", + "sphinx_panels", "sphinx_design", ] From c03e1f65f5f6b03dd4f770b75dc8215066401082 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Thu, 26 May 2022 15:43:03 -0400 Subject: [PATCH 09/14] typo --- ci/requirements/doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 6ca43fe78be..1d05daa7d80 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -33,7 +33,7 @@ dependencies: - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - sphinx-design - - sphinx_panels + - sphinx-panels - sphinx!=4.4.0 - zarr>=2.4 - pip: From acdd75b6b4213006f29190ea55557d6a85d2ffe4 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Mon, 30 May 2022 23:35:05 -0600 Subject: [PATCH 10/14] replace `sphinx-panels` with `sphinx-design` --- .gitignore | 4 ++ doc/conf.py | 114 ++++++++++++++++++++++++++++++++++- doc/gallery.rst | 100 +----------------------------- doc/gallery.yml | 46 ++++++++++++++ doc/team.rst | 79 +----------------------- doc/team.yml | 59 ++++++++++++++++++ doc/tutorials-and-videos.rst | 53 +--------------- doc/videos.yml | 31 ++++++++++ 8 files changed, 255 insertions(+), 231 deletions(-) create mode 100644 doc/gallery.yml create mode 100644 doc/team.yml create mode 100644 doc/videos.yml diff --git a/.gitignore b/.gitignore index 293e79fe806..21c18c17ff7 100644 --- a/.gitignore +++ b/.gitignore @@ -75,3 +75,7 @@ xarray/tests/data/*.grib.*.idx Icon* .ipynb_checkpoints +doc/team-panel.txt +doc/external-examples-gallery.txt +doc/notebooks-examples-gallery.txt +doc/videos-gallery.txt diff --git a/doc/conf.py b/doc/conf.py index 3e8cc2dbd10..8545c3cd643 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -15,14 +15,21 @@ import datetime import inspect import os +import pathlib import subprocess import sys from contextlib import suppress +from textwrap import dedent, indent import sphinx_autosummary_accessors +import yaml +from sphinx.application import Sphinx +from sphinx.util import logging import xarray +LOGGER = logging.getLogger("conf") + allowed_failures = set() print("python exec:", sys.executable) @@ -85,7 +92,6 @@ "sphinxext.opengraph", "sphinx_copybutton", "sphinxext.rediraffe", - "sphinx_panels", "sphinx_design", ] @@ -190,7 +196,7 @@ # General information about the project. project = "xarray" -copyright = "2014-%s, xarray Developers" % datetime.datetime.now().year +copyright = f"2014-{datetime.datetime.now().year}, xarray Developers" # The short X.Y version. version = xarray.__version__.split("+")[0] @@ -387,5 +393,107 @@ def html_page_context(app, pagename, templatename, context, doctree): context["theme_use_edit_page_button"] = False -def setup(app): +def update_team(app: Sphinx): + """Update the team members list.""" + + LOGGER.info("Updating team members page...") + + team = yaml.safe_load(pathlib.Path(app.srcdir, "team.yml").read_bytes()) + items = [] + for member in team: + item = f""" + .. grid-item-card:: + :link: https://github.com/{member['gh_login']} + + .. image:: {member['avatar']} + :alt: {member['name']} + +++ + {member['name']} + """ + items.append(item) + + items_md = indent(dedent("\n".join(items)), prefix=" ") + + markdown = f""" +.. grid:: 1 2 3 3 + :gutter: 2 + + {items_md} + """ + + pathlib.Path(app.srcdir, "team-panel.txt").write_text(markdown) + LOGGER.info("Team members page updated.") + + +def update_gallery(app: Sphinx): + """Update the gallery page.""" + + LOGGER.info("Updating gallery page...") + + gallery = yaml.safe_load(pathlib.Path(app.srcdir, "gallery.yml").read_bytes()) + + for key in gallery: + items = [ + f""" + .. grid-item-card:: + :link: {item['path']} + + .. image:: {item['thumbnail']} + :alt: {item['title']} + +++ + {item['title']} + """ + for item in gallery[key] + ] + + items_md = indent(dedent("\n".join(items)), prefix=" ") + markdown = f""" +.. grid:: 1 2 2 2 + :gutter: 2 + + {items_md} + """ + pathlib.Path(app.srcdir, f"{key}-gallery.txt").write_text(markdown) + LOGGER.info(f"{key} gallery page updated.") + LOGGER.info("Gallery page updated.") + + +def update_videos(app: Sphinx): + """Update the videos page.""" + + LOGGER.info("Updating videos page...") + + videos = yaml.safe_load(pathlib.Path(app.srcdir, "videos.yml").read_bytes()) + + items = [] + for video in videos: + + authors = " | ".join(video["authors"]) + item = f""" +.. grid-item-card:: {" ".join(video["title"].split())} + :text-align: center + + .. raw:: html + + {video['src']} + +++ + {authors} + """ + items.append(item) + + items_md = indent(dedent("\n".join(items)), prefix=" ") + markdown = f""" +.. grid:: 1 2 2 2 + :gutter: 2 + + {items_md} + """ + pathlib.Path(app.srcdir, "videos-gallery.txt").write_text(markdown) + LOGGER.info("Videos page updated.") + + +def setup(app: Sphinx): app.connect("html-page-context", html_page_context) + app.connect("builder-inited", update_team) + app.connect("builder-inited", update_gallery) + app.connect("builder-inited", update_videos) diff --git a/doc/gallery.rst b/doc/gallery.rst index 22cf0c1c379..61ec45c7bda 100644 --- a/doc/gallery.rst +++ b/doc/gallery.rst @@ -10,75 +10,7 @@ Contributions are highly welcomed and appreciated. So, if you are interested in Notebook Examples ----------------- -.. panels:: - :column: text-center col-lg-6 col-md-6 col-sm-12 col-xs-12 p-2 - :card: +my-2 - :img-top-cls: w-75 m-auto p-2 - :body: d-none - - --- - :img-top: _static/thumbnails/toy-weather-data.png - ++++ - .. link-button:: examples/weather-data - :type: ref - :text: Toy weather data - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/monthly-means.png - ++++ - .. link-button:: examples/monthly-means - :type: ref - :text: Calculating Seasonal Averages from Timeseries of Monthly Means - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/area_weighted_temperature.png - ++++ - .. link-button:: examples/area_weighted_temperature - :type: ref - :text: Compare weighted and unweighted mean temperature - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/multidimensional-coords.png - ++++ - .. link-button:: examples/multidimensional-coords - :type: ref - :text: Working with Multidimensional Coordinates - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/visualization_gallery.png - ++++ - .. link-button:: examples/visualization_gallery - :type: ref - :text: Visualization Gallery - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/ROMS_ocean_model.png - ++++ - .. link-button:: examples/ROMS_ocean_model - :type: ref - :text: ROMS Ocean Model Example - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/thumbnails/ERA5-GRIB-example.png - ++++ - .. link-button:: examples/ERA5-GRIB-example - :type: ref - :text: GRIB Data Example - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/dataset-diagram-square-logo.png - ++++ - .. link-button:: examples/apply_ufunc_vectorize_1d - :type: ref - :text: Applying unvectorized functions with apply_ufunc - :classes: btn-outline-dark btn-block stretched-link +.. include:: notebooks-examples-gallery.txt .. toctree:: @@ -100,32 +32,4 @@ External Examples ----------------- -.. panels:: - :column: text-center col-lg-6 col-md-6 col-sm-12 col-xs-12 p-2 - :card: +my-2 - :img-top-cls: w-75 m-auto p-2 - :body: d-none - - --- - :img-top: _static/dataset-diagram-square-logo.png - ++++ - .. link-button:: https://corteva.github.io/rioxarray/stable/examples/examples.html - :type: url - :text: Managing raster data with rioxarray - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: https://avatars.githubusercontent.com/u/60833341?s=200&v=4 - ++++ - .. link-button:: https://gallery.pangeo.io/ - :type: url - :text: Xarray and dask on the cloud with Pangeo - :classes: btn-outline-dark btn-block stretched-link - - --- - :img-top: _static/dataset-diagram-square-logo.png - ++++ - .. link-button:: https://examples.dask.org/xarray.html - :type: url - :text: Xarray with Dask Arrays - :classes: btn-outline-dark btn-block stretched-link +.. include:: external-examples-gallery.txt diff --git a/doc/gallery.yml b/doc/gallery.yml new file mode 100644 index 00000000000..201d226e776 --- /dev/null +++ b/doc/gallery.yml @@ -0,0 +1,46 @@ +notebooks-examples: + - title: Toy weather data + path: examples/weather-data + thumbnail: _static/thumbnails/toy-weather-data.png + + - title: Calculating Seasonal Averages from Timeseries of Monthly Means + path: examples/monthly-means + thumbnail: _static/thumbnails/monthly-means.png + + - title: Compare weighted and unweighted mean temperature + path: examples/area_weighted_temperature + thumbnail: _static/thumbnails/area_weighted_temperature.png + + - title: Working with Multidimensional Coordinates + path: examples/multidimensional-coords + thumbnail: _static/thumbnails/multidimensional-coords.png + + - title: Visualization Gallery + path: examples/visualization_gallery + thumbnail: _static/thumbnails/visualization_gallery.png + + - title: GRIB Data Example + path: examples/ERA5-GRIB-example + thumbnail: _static/thumbnails/ERA5-GRIB-example.png + + - title: Applying unvectorized functions with apply_ufunc + path: examples/apply_ufunc_vectorize_1d + thumbnail: _static/dataset-diagram-square-logo.png + +external-examples: + + - title: Managing raster data with rioxarray + path: https://corteva.github.io/rioxarray/stable/examples/examples.html + thumbnail: _static/dataset-diagram-square-logo.png + + - title: Xarray and dask on the cloud with Pangeo + path: https://gallery.pangeo.io/ + thumbnail: https://avatars.githubusercontent.com/u/60833341?s=200&v=4 + + - title: Xarray with Dask Arrays + path: https://examples.dask.org/xarray.html_ + thumbnail: _static/dataset-diagram-square-logo.png + + - title: Project Pythia Foundations Book + path: https://foundations.projectpythia.org/core/xarray.html + thumbnail: https://raw.githubusercontent.com/ProjectPythia/projectpythia.github.io/main/portal/_static/images/logos/pythia_logo-blue-btext-twocolor.svg diff --git a/doc/team.rst b/doc/team.rst index 937d16627c7..c941afa51bf 100644 --- a/doc/team.rst +++ b/doc/team.rst @@ -8,84 +8,7 @@ Xarray core developers are responsible for the ongoing organizational maintenanc The current core developers team comprises: -.. panels:: - :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2 - :card: text-center - - --- - .. image:: https://avatars.githubusercontent.com/u/1217238?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/shoyer,"Stephan Hoyer",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/1197350?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/rabernat,"Ryan Abernathey",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/2443309?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/jhamman,"Joe Hamman",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/4160723?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/benbovy,"Benoit Bovy",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/10050469?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/fmaussion,"Fabien Maussion",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/6815844?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/fujiisoup,"Keisuke Fujii",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/5635139?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/max-sixty,"Maximilian Roos",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/2448579?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/dcherian,"Deepak Cherian",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/6628425?v=4 - +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/spencerkclark,"Spencer Clark",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/35968931?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/TomNicholas,"Tom Nicholas",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/6213168?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/crusaderky,"Guido Imperiale",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/14808389?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/keewis,"Justus Magin",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/10194086?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/mathause,"Mathias Hauser",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/13301940?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/andersy005,"Anderson Banihirwe",cls=btn badge-light` - - --- - .. image:: https://avatars.githubusercontent.com/u/14371165?v=4 - ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - :link-badge:`https://github.com/Illviljan,"Jimmy Westling",cls=btn badge-light` +.. include:: team_panel.txt The full list of contributors is on our `GitHub Contributors Page `__. diff --git a/doc/team.yml b/doc/team.yml new file mode 100644 index 00000000000..56ccc457420 --- /dev/null +++ b/doc/team.yml @@ -0,0 +1,59 @@ +- name: Stephan Hoyer + gh_login: shoyer + avatar: https://avatars.githubusercontent.com/u/1217238?v=4 + +- name: Joe Hamman + gh_login: jhamman + avatar: https://avatars.githubusercontent.com/u/2443309?v=4 + +- name: Ryan Abernathey + gh_login: rabernat + avatar: https://avatars.githubusercontent.com/u/1197350?v=4 + +- name: Benoit Bovy + gh_login: genbovy + avatar: https://avatars.githubusercontent.com/u/4160723?v=4 + +- name: Fabien Maussion + gh_login: fmaussion + avatar: https://avatars.githubusercontent.com/u/10050469?v=4 + +- name: Keisuke Fujii + gh_login: fujiisoup + avatar: https://avatars.githubusercontent.com/u/6815844?v=4 + +- name: Maximilian Roos + gh_login: max-sixty + avatar: https://avatars.githubusercontent.com/u/5635139?v=4 + +- name: Deepak Cherian + gh_login: dcherian + avatar: https://avatars.githubusercontent.com/u/2448579?v=4 + +- name: Spencer Clark + gh_login: spencerkclark + avatar: https://avatars.githubusercontent.com/u/6628425?v=4 + +- name: Tom Nicholas + gh_login: TomNicholas + avatar: https://avatars.githubusercontent.com/u/35968931?v=4 + +- name: Guido Imperiale + gh_login: crusaderky + avatar: https://avatars.githubusercontent.com/u/6213168?v=4 + +- name: Justus Magin + gh_login: keewis + avatar: https://avatars.githubusercontent.com/u/14808389?v=4 + +- name: Mathias Hauser + gh_login: mathause + avatar: https://avatars.githubusercontent.com/u/10194086?v=4 + +- name: Anderson Banihirwe + gh_login: andersy005 + avatar: https://avatars.githubusercontent.com/u/13301940?v=4 + +- name: Jimmy Westling + gh_login: Illviljan + avatar: https://avatars.githubusercontent.com/u/14371165?v=4 diff --git a/doc/tutorials-and-videos.rst b/doc/tutorials-and-videos.rst index 37b8d1968eb..7a9e524340b 100644 --- a/doc/tutorials-and-videos.rst +++ b/doc/tutorials-and-videos.rst @@ -15,59 +15,8 @@ Tutorials Videos ------- -.. panels:: - :card: text-center +.. include:: videos-gallery.txt - --- - Xdev Python Tutorial Seminar Series 2022 Thinking with Xarray : High-level computation patterns | Deepak Cherian - ^^^ - .. raw:: html - - - - --- - Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (2 of 2) | Anderson Banihirwe - ^^^ - .. raw:: html - - - - --- - Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (1 of 2) | Anderson Banihirwe - ^^^ - .. raw:: html - - - - --- - Xarray's virtual tutorial | October 2020 | Anderson Banihirwe, Deepak Cherian, and Martin Durant - ^^^ - .. raw:: html - - - - --- - Xarray's Tutorial presented at the 2020 SciPy Conference | Joe Hamman, Ryan Abernathey, - Deepak Cherian, and Stephan Hoyer - ^^^ - .. raw:: html - - - - --- - Scipy 2015 talk introducing xarray to a general audience | Stephan Hoyer - ^^^ - .. raw:: html - - - - --- - 2015 Unidata Users Workshop talk and tutorial with (`with answers`_) introducing - xarray to users familiar with netCDF | Stephan Hoyer - ^^^ - .. raw:: html - - Books, Chapters and Articles ----------------------------- diff --git a/doc/videos.yml b/doc/videos.yml new file mode 100644 index 00000000000..0b7dd4cd4c8 --- /dev/null +++ b/doc/videos.yml @@ -0,0 +1,31 @@ +- title: "Xdev Python Tutorial Seminar Series 2022 Thinking with Xarray : High-level computation patterns" + src: '' + authors: + - Deepak Cherian +- title: "Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (2 of 2)" + src: '' + authors: + - Anderson Banihirwe + +- title: "Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (1 of 2)" + src: '' + authors: + - Anderson Banihirwe + +- title: "Xarray's Tutorial presented at the 2020 SciPy Conference" + src: ' ' + authors: + - Joe Hamman + - Deepak Cherian + - Ryan Abernathey + - Stephan Hoyer + +- title: "Scipy 2015 talk introducing xarray to a general audience" + src: '' + authors: + - Stephan Hoyer + +- title: " 2015 Unidata Users Workshop talk and tutorial with (`with answers`_) introducing xarray to users familiar with netCDF" + src: '' + authors: + - Stephan Hoyer From 8eb144768f83bc8dabb0c3b47e8fad963604b411 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Mon, 30 May 2022 23:36:20 -0600 Subject: [PATCH 11/14] remove sphinx-panels --- ci/requirements/doc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 1d05daa7d80..437c493c92c 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -33,7 +33,6 @@ dependencies: - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - sphinx-design - - sphinx-panels - sphinx!=4.4.0 - zarr>=2.4 - pip: From 9834c21e7a64a727a7d68499adfdfccc0d5733c9 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Mon, 30 May 2022 23:44:41 -0600 Subject: [PATCH 12/14] Add blog --- doc/index.rst | 4 +++- doc/team.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 8e8cbf4df73..973f4c2c6d1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,7 +11,9 @@ efficient, and fun! `Discussions `__ | `Releases `__ | `Stack Overflow `__ | -`Mailing List `__ +`Mailing List `__ | +`Blog `__ + .. grid:: 1 1 2 2 :gutter: 2 diff --git a/doc/team.rst b/doc/team.rst index c941afa51bf..ce0cb33c6ba 100644 --- a/doc/team.rst +++ b/doc/team.rst @@ -8,7 +8,7 @@ Xarray core developers are responsible for the ongoing organizational maintenanc The current core developers team comprises: -.. include:: team_panel.txt +.. include:: team-panel.txt The full list of contributors is on our `GitHub Contributors Page `__. From 24c9a052e8d00fcde6d3f2568de53b632a16c923 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Tue, 31 May 2022 00:06:02 -0600 Subject: [PATCH 13/14] formatting only --- doc/gallery.yml | 1 - doc/videos.yml | 23 +++++++++++++++-------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/doc/gallery.yml b/doc/gallery.yml index 201d226e776..1f122eac378 100644 --- a/doc/gallery.yml +++ b/doc/gallery.yml @@ -28,7 +28,6 @@ notebooks-examples: thumbnail: _static/dataset-diagram-square-logo.png external-examples: - - title: Managing raster data with rioxarray path: https://corteva.github.io/rioxarray/stable/examples/examples.html thumbnail: _static/dataset-diagram-square-logo.png diff --git a/doc/videos.yml b/doc/videos.yml index 0b7dd4cd4c8..62c89563a56 100644 --- a/doc/videos.yml +++ b/doc/videos.yml @@ -5,27 +5,34 @@ - title: "Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (2 of 2)" src: '' authors: - - Anderson Banihirwe + - Anderson Banihirwe - title: "Xdev Python Tutorial Seminar Series 2021 seminar introducing xarray (1 of 2)" src: '' authors: - - Anderson Banihirwe + - Anderson Banihirwe + +- title: "Xarray's 2020 virtual tutorial" + src: '' + authors: + - Anderson Banihirwe + - Deepak Cherian + - Martin Durant - title: "Xarray's Tutorial presented at the 2020 SciPy Conference" src: ' ' authors: - - Joe Hamman - - Deepak Cherian - - Ryan Abernathey - - Stephan Hoyer + - Joe Hamman + - Deepak Cherian + - Ryan Abernathey + - Stephan Hoyer - title: "Scipy 2015 talk introducing xarray to a general audience" src: '' authors: - - Stephan Hoyer + - Stephan Hoyer - title: " 2015 Unidata Users Workshop talk and tutorial with (`with answers`_) introducing xarray to users familiar with netCDF" src: '' authors: - - Stephan Hoyer + - Stephan Hoyer From f9f0c7cfc4438207121d572989397f9e3a6526b9 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Tue, 31 May 2022 09:36:28 -0600 Subject: [PATCH 14/14] center the text --- doc/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 8545c3cd643..7e28953bc7f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -403,6 +403,7 @@ def update_team(app: Sphinx): for member in team: item = f""" .. grid-item-card:: + :text-align: center :link: https://github.com/{member['gh_login']} .. image:: {member['avatar']} @@ -436,6 +437,7 @@ def update_gallery(app: Sphinx): items = [ f""" .. grid-item-card:: + :text-align: center :link: {item['path']} .. image:: {item['thumbnail']}