diff --git a/.gitignore b/.gitignore index 5f02700de37..90f4a10ed5f 100644 --- a/.gitignore +++ b/.gitignore @@ -65,10 +65,11 @@ dask-worker-space/ # xarray specific doc/_build -doc/generated +generated/ xarray/tests/data/*.grib.*.idx # Sync tools Icon* .ipynb_checkpoints +doc/rasm.zarr diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 47b3cb9eb70..fe6dead5434 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -20,16 +20,20 @@ dependencies: - numba - numpy>=1.17 - pandas>=1.0 + - pip + - pydata-sphinx-theme>=0.4.3 - rasterio>=1.1 - seaborn - setuptools - sparse - - sphinx>=3.3 - - sphinx_rtd_theme>=0.4 - sphinx-autosummary-accessors + - sphinx-book-theme >= 0.0.38 + - sphinx-copybutton + - sphinx-panels + - sphinx>=3.3 - zarr>=2.4 - - pip - pip: - - scanpydoc + - sphinxext-rediraffe + - sphinxext-opengraph # relative to this file. Needs to be editable to be accepted. - -e ../.. diff --git a/doc/Makefile b/doc/Makefile index d88a8a59c39..8b08d3a2dbe 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -19,6 +19,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @echo " rtdhtml Build html using same settings used on ReadtheDocs" @echo " livehtml Make standalone HTML files and rebuild the documentation when a change is detected. Also includes a livereload enabled web server" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -58,6 +59,13 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +.PHONY: rtdhtml +rtdhtml: + $(SPHINXBUILD) -T -j auto -E -W --keep-going -b html -d $(BUILDDIR)/doctrees -D language=en . $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + + .PHONY: livehtml livehtml: # @echo "$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html" diff --git a/doc/_static/style.css b/doc/_static/style.css index b7d30f429cf..66983bb1b38 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -1,22 +1,3 @@ -@import url("theme.css"); - -.wy-side-nav-search>a img.logo, -.wy-side-nav-search .wy-dropdown>a img.logo { - width: 12rem -} - -.wy-side-nav-search { - background-color: #eee; -} - -.wy-side-nav-search>div.version { - display: none; -} - -.wy-nav-top { - background-color: #555; -} - table.colwidths-given { table-layout: fixed; width: 100%; @@ -25,3 +6,15 @@ table.docutils td { white-space: unset; word-wrap: break-word; } + +/* Reduce left and right margins */ + +.container, .container-lg, .container-md, .container-sm, .container-xl { + max-width: 1600px !important; +} + +/* Make sidebar sticky */ + +.bd-sidebar { + position: sticky !important; +} diff --git a/doc/_static/thumbnails/ERA5-GRIB-example.png b/doc/_static/thumbnails/ERA5-GRIB-example.png new file mode 100644 index 00000000000..412dd28a6d9 Binary files /dev/null and b/doc/_static/thumbnails/ERA5-GRIB-example.png differ diff --git a/doc/_static/thumbnails/ROMS_ocean_model.png b/doc/_static/thumbnails/ROMS_ocean_model.png new file mode 100644 index 00000000000..9333335d1ef Binary files /dev/null and b/doc/_static/thumbnails/ROMS_ocean_model.png differ diff --git a/doc/_static/thumbnails/area_weighted_temperature.png b/doc/_static/thumbnails/area_weighted_temperature.png new file mode 100644 index 00000000000..7d3604d7c2b Binary files /dev/null and b/doc/_static/thumbnails/area_weighted_temperature.png differ diff --git a/doc/_static/thumbnails/monthly-means.png b/doc/_static/thumbnails/monthly-means.png new file mode 100644 index 00000000000..da5691848b0 Binary files /dev/null and b/doc/_static/thumbnails/monthly-means.png differ diff --git a/doc/_static/thumbnails/multidimensional-coords.png b/doc/_static/thumbnails/multidimensional-coords.png new file mode 100644 index 00000000000..b0d893d6894 Binary files /dev/null and b/doc/_static/thumbnails/multidimensional-coords.png differ diff --git a/doc/_static/thumbnails/toy-weather-data.png b/doc/_static/thumbnails/toy-weather-data.png new file mode 100644 index 00000000000..64ac0a4b021 Binary files /dev/null and b/doc/_static/thumbnails/toy-weather-data.png differ diff --git a/doc/_static/thumbnails/visualization_gallery.png b/doc/_static/thumbnails/visualization_gallery.png new file mode 100644 index 00000000000..9e6c2436be5 Binary files /dev/null and b/doc/_static/thumbnails/visualization_gallery.png differ diff --git a/doc/_templates/autosummary/base.rst b/doc/_templates/autosummary/base.rst deleted file mode 100644 index 53f2a29c193..00000000000 --- a/doc/_templates/autosummary/base.rst +++ /dev/null @@ -1,3 +0,0 @@ -:github_url: {{ fullname | github_url | escape_underscores }} - -{% extends "!autosummary/base.rst" %} diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html deleted file mode 100644 index 4c57ba83056..00000000000 --- a/doc/_templates/layout.html +++ /dev/null @@ -1,2 +0,0 @@ -{% extends "!layout.html" %} -{% set css_files = css_files + ["_static/style.css"] %} diff --git a/doc/conf.py b/doc/conf.py index db7229cfa61..86ff3768411 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,14 +13,13 @@ import datetime +import inspect import os -import pathlib import subprocess import sys from contextlib import suppress import sphinx_autosummary_accessors -from jinja2.defaults import DEFAULT_FILTERS import xarray @@ -80,7 +79,11 @@ "IPython.sphinxext.ipython_console_highlighting", "nbsphinx", "sphinx_autosummary_accessors", - "scanpydoc.rtd_github_links", + "sphinx.ext.linkcode", + "sphinx_panels", + "sphinxext.opengraph", + "sphinx_copybutton", + "sphinxext.rediraffe", ] extlinks = { @@ -88,6 +91,12 @@ "pull": ("https://github.com/pydata/xarray/pull/%s", "PR"), } +# sphinx-copybutton configurations +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True + +# nbsphinx configurations + nbsphinx_timeout = 600 nbsphinx_execute = "always" nbsphinx_prolog = """ @@ -100,20 +109,12 @@ """ autosummary_generate = True - -# for scanpydoc's jinja filter -project_dir = pathlib.Path(__file__).parent.parent -html_context = { - "github_user": "pydata", - "github_repo": "xarray", - "github_version": "master", -} - autodoc_typehints = "none" +# Napoleon configurations + napoleon_google_docstring = False napoleon_numpy_docstring = True - napoleon_use_param = False napoleon_use_rtype = False napoleon_preprocess_types = True @@ -167,17 +168,13 @@ "pd.NaT": "~pandas.NaT", } -numpydoc_class_members_toctree = True -numpydoc_show_class_members = False # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates", sphinx_autosummary_accessors.templates_path] # The suffix of source filenames. -source_suffix = ".rst" +# source_suffix = ".rst" -# The encoding of source files. -# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = "index" @@ -186,19 +183,11 @@ project = "xarray" copyright = "2014-%s, xarray Developers" % datetime.datetime.now().year -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# # The short X.Y version. version = xarray.__version__.split("+")[0] # The full version, including alpha/beta/rc tags. release = xarray.__version__ -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: # today = '' @@ -209,51 +198,45 @@ # directories to ignore when looking for source files. exclude_patterns = ["_build", "**.ipynb_checkpoints"] -# The reST default role (used for this markup: `text`) to use for all -# documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - # -- Options for HTML output ---------------------------------------------- - # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +html_theme = "sphinx_book_theme" +html_title = "" + +html_context = { + "github_user": "pydata", + "github_repo": "xarray", + "github_version": "master", + "doc_path": "doc", +} # 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 = {"logo_only": True} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None +html_theme_options = dict( + # analytics_id='' this is configured in rtfd.io + # canonical_url="", + repository_url="https://github.com/pydata/xarray", + repository_branch="master", + path_to_docs="doc", + use_edit_page_button=True, + use_repository_button=True, + use_issues_button=True, + home_page_in_toc=False, + extra_navbar="", + navbar_footer_text="", + extra_footer="""

Xarray is a fiscally sponsored project of NumFOCUS, + a nonprofit dedicated to supporting the open-source scientific computing community.
+ Theme by the Executable Book Project

""", + twitter_url="https://twitter.com/xarray_devs", +) -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -268,6 +251,42 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_css_files = ["style.css"] + + +# configuration for sphinxext.opengraph +ogp_site_url = "https://xarray.pydata.org/en/latest/" +ogp_image = "https://xarray.pydata.org/en/stable/_static/dataset-diagram-logo.png" +ogp_custom_meta_tags = [ + '', + '', +] + +# Redirects for pages that were moved to new locations + +rediraffe_redirects = { + "terminology.rst": "user-guide/terminology.rst", + "data-structures.rst": "user-guide/data-structures.rst", + "indexing.rst": "user-guide/indexing.rst", + "interpolation.rst": "user-guide/interpolation.rst", + "computation.rst": "user-guide/computation.rst", + "groupby.rst": "user-guide/groupby.rst", + "reshaping.rst": "user-guide/reshaping.rst", + "combining.rst": "user-guide/combining.rst", + "time-series.rst": "user-guide/time-series.rst", + "weather-climate.rst": "user-guide/weather-climate.rst", + "pandas.rst": "user-guide/pandas.rst", + "io.rst": "user-guide/io.rst", + "dask.rst": "user-guide/dask.rst", + "plotting.rst": "user-guide/plotting.rst", + "duckarrays.rst": "user-guide/duckarrays.rst", + "related-projects.rst": "ecosystem.rst", + "faq.rst": "getting-started-guide/faq.rst", + "why-xarray.rst": "getting-started-guide/why-xarray.rst", + "installing.rst": "getting-started-guide/installing.rst", + "quick-overview.rst": "getting-started-guide/quick-overview.rst", +} # Sometimes the savefig directory doesn't exist and needs to be created # https://github.com/ipython/ipython/issues/8733 @@ -278,135 +297,15 @@ if not os.path.exists(ipython_savefig_dir): os.makedirs(ipython_savefig_dir) -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = today_fmt -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - # Output file base name for HTML help builder. htmlhelp_basename = "xarraydoc" -# -- Options for LaTeX output --------------------------------------------- - -# latex_elements = { -# # The paper size ('letterpaper' or 'a4paper'). -# # 'papersize': 'letterpaper', -# # The font size ('10pt', '11pt' or '12pt'). -# # 'pointsize': '10pt', -# # Additional stuff for the LaTeX preamble. -# # 'preamble': '', -# } - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -# latex_documents = [ -# ("index", "xarray.tex", "xarray Documentation", "xarray Developers", "manual") -# ] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -# man_pages = [("index", "xarray", "xarray Documentation", ["xarray Developers"], 1)] - -# If true, show URL addresses after external links. -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -# texinfo_documents = [ -# ( -# "index", -# "xarray", -# "xarray Documentation", -# "xarray Developers", -# "xarray", -# "N-D labeled arrays and datasets in Python.", -# "Miscellaneous", -# ) -# ] - -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# texinfo_no_detailmenu = False - - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), @@ -423,9 +322,61 @@ } -def escape_underscores(string): - return string.replace("_", r"\_") +# based on numpy doc/source/conf.py +def linkcode_resolve(domain, info): + """ + Determine the URL corresponding to Python object + """ + if domain != "py": + return None + + modname = info["module"] + fullname = info["fullname"] + + submod = sys.modules.get(modname) + if submod is None: + return None + + obj = submod + for part in fullname.split("."): + try: + obj = getattr(obj, part) + except AttributeError: + return None + + try: + fn = inspect.getsourcefile(inspect.unwrap(obj)) + except TypeError: + fn = None + if not fn: + return None + + try: + source, lineno = inspect.getsourcelines(obj) + except OSError: + lineno = None + + if lineno: + linespec = f"#L{lineno}-L{lineno + len(source) - 1}" + else: + linespec = "" + + fn = os.path.relpath(fn, start=os.path.dirname(xarray.__file__)) + + if "+" in xarray.__version__: + return f"https://github.com/pydata/xarray/blob/master/xarray/{fn}{linespec}" + else: + return ( + f"https://github.com/pydata/xarray/blob/" + f"v{xarray.__version__}/xarray/{fn}{linespec}" + ) + + +def html_page_context(app, pagename, templatename, context, doctree): + # Disable edit button for docstring generated pages + if "generated" in pagename: + context["theme_use_edit_page_button"] = False def setup(app): - DEFAULT_FILTERS["escape_underscores"] = escape_underscores + app.connect("html-page-context", html_page_context) diff --git a/doc/contributing.rst b/doc/contributing.rst index 439791cbbd6..345443001a0 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -4,8 +4,6 @@ Contributing to xarray ********************** -.. contents:: Table of contents: - :local: .. note:: diff --git a/doc/related-projects.rst b/doc/ecosystem.rst similarity index 99% rename from doc/related-projects.rst rename to doc/ecosystem.rst index 0a010195d6d..01f5c29b9f5 100644 --- a/doc/related-projects.rst +++ b/doc/ecosystem.rst @@ -1,4 +1,4 @@ -.. _related-projects: +.. _ecosystem: Xarray related projects ----------------------- diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index 102138b6e4e..00000000000 --- a/doc/examples.rst +++ /dev/null @@ -1,29 +0,0 @@ -Examples -======== - -.. toctree:: - :maxdepth: 1 - - examples/weather-data - examples/monthly-means - examples/area_weighted_temperature - examples/multidimensional-coords - examples/visualization_gallery - examples/ROMS_ocean_model - examples/ERA5-GRIB-example - -Using apply_ufunc ------------------- -.. toctree:: - :maxdepth: 1 - - examples/apply_ufunc_vectorize_1d - -External Examples ------------------ -.. toctree:: - :maxdepth: 2 - - Managing raster data with rioxarray - Xarray with dask - Xarray and dask on the cloud with Pangeo diff --git a/doc/gallery.rst b/doc/gallery.rst new file mode 100644 index 00000000000..9e5284cc2ee --- /dev/null +++ b/doc/gallery.rst @@ -0,0 +1,130 @@ +Gallery +======= + +Here's a list of examples on how to use xarray. We will be adding more examples soon. +Contributions are highly welcomed and appreciated. So, if you are interested in contributing, please consult the +:doc:`contributing` guide. + + + +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 + + +.. toctree:: + :maxdepth: 1 + :hidden: + + examples/weather-data + examples/monthly-means + examples/area_weighted_temperature + examples/multidimensional-coords + examples/visualization_gallery + examples/ROMS_ocean_model + examples/ERA5-GRIB-example + examples/apply_ufunc_vectorize_1d + + +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:: http://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 diff --git a/doc/faq.rst b/doc/getting-started-guide/faq.rst similarity index 99% rename from doc/faq.rst rename to doc/getting-started-guide/faq.rst index a2151cc4b37..4cf3cc5b63d 100644 --- a/doc/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -185,7 +185,7 @@ for more details. What other projects leverage xarray? ------------------------------------ -See section :ref:`related-projects`. +See section :ref:`ecosystem`. How should I cite xarray? ------------------------- diff --git a/doc/getting-started-guide/index.rst b/doc/getting-started-guide/index.rst new file mode 100644 index 00000000000..20fd49fb2c4 --- /dev/null +++ b/doc/getting-started-guide/index.rst @@ -0,0 +1,15 @@ +################ +Getting Started +################ + +The getting started guide aims to get you using xarray productively as quickly as possible. +It is designed as an entry point for new users, and it provided an introduction to xarray's main concepts. + +.. toctree:: + :maxdepth: 2 + :hidden: + + why-xarray + installing + quick-overview + faq diff --git a/doc/installing.rst b/doc/getting-started-guide/installing.rst similarity index 92% rename from doc/installing.rst rename to doc/getting-started-guide/installing.rst index 396f24b9151..fb88c223c98 100644 --- a/doc/installing.rst +++ b/doc/getting-started-guide/installing.rst @@ -144,15 +144,15 @@ being updated in the default channel. If you don't use conda, be sure you have the required dependencies (numpy and pandas) installed first. Then, install xarray with pip:: - $ pip install xarray + $ python -m pip install xarray We also maintain other dependency sets for different subsets of functionality:: - $ pip install "xarray[io]" # Install optional dependencies for handling I/O - $ pip install "xarray[accel]" # Install optional dependencies for accelerating xarray - $ pip install "xarray[parallel]" # Install optional dependencies for dask arrays - $ pip install "xarray[viz]" # Install optional dependencies for visualization - $ pip install "xarray[complete]" # Install all the above + $ python -m pip install "xarray[io]" # Install optional dependencies for handling I/O + $ python -m pip install "xarray[accel]" # Install optional dependencies for accelerating xarray + $ python -m pip install "xarray[parallel]" # Install optional dependencies for dask arrays + $ python -m pip install "xarray[viz]" # Install optional dependencies for visualization + $ python -m pip install "xarray[complete]" # Install all the above The above commands should install most of the `optional dependencies`_. However, some packages which are either not listed on PyPI or require extra @@ -160,7 +160,7 @@ installation steps are excluded. To know which dependencies would be installed, take a look at the ``[options.extras_require]`` section in ``setup.cfg``: -.. literalinclude:: ../setup.cfg +.. literalinclude:: ../../setup.cfg :language: ini :start-at: [options.extras_require] :end-before: [options.package_data] diff --git a/doc/quick-overview.rst b/doc/getting-started-guide/quick-overview.rst similarity index 100% rename from doc/quick-overview.rst rename to doc/getting-started-guide/quick-overview.rst diff --git a/doc/why-xarray.rst b/doc/getting-started-guide/why-xarray.rst similarity index 100% rename from doc/why-xarray.rst rename to doc/getting-started-guide/why-xarray.rst diff --git a/doc/index.rst b/doc/index.rst index ee44d0ad4d9..c4c9d89264b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,122 +22,56 @@ computing. .. _dask: http://dask.org .. _netCDF: http://www.unidata.ucar.edu/software/netcdf -Documentation -------------- - -**Getting Started** - -* :doc:`why-xarray` -* :doc:`faq` -* :doc:`quick-overview` -* :doc:`examples` -* :doc:`installing` .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :hidden: - :caption: Getting Started - - why-xarray - faq - quick-overview - examples - installing - -**User Guide** - -* :doc:`terminology` -* :doc:`data-structures` -* :doc:`indexing` -* :doc:`interpolation` -* :doc:`computation` -* :doc:`groupby` -* :doc:`reshaping` -* :doc:`combining` -* :doc:`time-series` -* :doc:`weather-climate` -* :doc:`pandas` -* :doc:`io` -* :doc:`dask` -* :doc:`plotting` -* :doc:`duckarrays` + :caption: For users + + Getting Started + User Guide + Gallery + Tutorials & Videos + API Reference + How do I ... + Ecosystem .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :hidden: - :caption: User Guide - - terminology - data-structures - indexing - interpolation - computation - groupby - reshaping - combining - time-series - weather-climate - pandas - io - dask - plotting - duckarrays - -**Help & reference** - -* :doc:`whats-new` -* :doc:`howdoi` -* :doc:`api` -* :doc:`internals` -* :doc:`roadmap` -* :doc:`contributing` -* :doc:`related-projects` + :caption: For developers/contributors + + Contributing Guide + Xarray Internals + Development Roadmap + Team + What’s New + GitHub repository .. toctree:: :maxdepth: 1 :hidden: - :caption: Help & reference + :caption: Community + + GitHub discussions + StackOverflow - whats-new - howdoi - api - internals - roadmap - contributing - related-projects -See also --------- -- `Xarray's Tutorial`_ presented at the 2020 SciPy Conference (`video recording`_). -- Stephan Hoyer and Joe Hamman's `Journal of Open Research Software paper`_ describing the xarray project. -- The `UW eScience Institute's Geohackweek`_ tutorial on xarray for geospatial data scientists. -- Stephan Hoyer's `SciPy2015 talk`_ introducing xarray to a general audience. -- Stephan Hoyer's `2015 Unidata Users Workshop talk`_ and `tutorial`_ (`with answers`_) introducing - xarray to users familiar with netCDF. -- `Nicolas Fauchereau's tutorial`_ on xarray for netCDF users. - -.. _Xarray's Tutorial: https://xarray-contrib.github.io/xarray-tutorial/ -.. _video recording: https://youtu.be/mecN-Ph_-78 -.. _Journal of Open Research Software paper: http://doi.org/10.5334/jors.148 -.. _UW eScience Institute's Geohackweek : https://geohackweek.github.io/nDarrays/ -.. _SciPy2015 talk: https://www.youtube.com/watch?v=X0pAhJgySxk -.. _2015 Unidata Users Workshop talk: https://www.youtube.com/watch?v=J9ypQOnt5l8 -.. _tutorial: https://github.com/Unidata/unidata-users-workshop/blob/master/notebooks/xray-tutorial.ipynb -.. _with answers: https://github.com/Unidata/unidata-users-workshop/blob/master/notebooks/xray-tutorial-with-answers.ipynb -.. _Nicolas Fauchereau's tutorial: http://nbviewer.iPython.org/github/nicolasfauchereau/metocean/blob/master/notebooks/xray.ipynb Get in touch ------------ -- Ask usage questions ("How do I?") on `StackOverflow`_. +- 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 the `mailing list`_. + interest to xarray users, use `GitHub discussions`_ or the `mailing list`_. -.. _StackOverFlow: http://stackoverflow.com/questions/tagged/python-xarray +.. _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: http://github.com/pydata/xarray +.. _on GitHub: https://github.com/pydata/xarray NumFOCUS -------- diff --git a/doc/internals/duck-arrays-integration.rst b/doc/internals/duck-arrays-integration.rst new file mode 100644 index 00000000000..eb5c4d8592f --- /dev/null +++ b/doc/internals/duck-arrays-integration.rst @@ -0,0 +1,51 @@ + +.. _internals.duck_arrays: + +Integrating with duck arrays +============================= + +.. warning:: + + This is a experimental feature. + +xarray can wrap custom :term:`duck array` objects as long as they define numpy's +``shape``, ``dtype`` and ``ndim`` properties and the ``__array__``, +``__array_ufunc__`` and ``__array_function__`` methods. + +In certain situations (e.g. when printing the collapsed preview of +variables of a ``Dataset``), xarray will display the repr of a :term:`duck array` +in a single line, truncating it to a certain number of characters. If that +would drop too much information, the :term:`duck array` may define a +``_repr_inline_`` method that takes ``max_width`` (number of characters) as an +argument: + +.. code:: python + + class MyDuckArray: + ... + + def _repr_inline_(self, max_width): + """ format to a single line with at most max_width characters """ + ... + + ... + +To avoid duplicated information, this method must omit information about the shape and +:term:`dtype`. For example, the string representation of a ``dask`` array or a +``sparse`` matrix would be: + +.. ipython:: python + + import dask.array as da + import xarray as xr + import sparse + + a = da.linspace(0, 1, 20, chunks=2) + a + + b = np.eye(10) + b[[5, 7, 3, 0], [6, 8, 2, 9]] = 2 + b = sparse.COO.from_numpy(b) + b + + xr.Dataset({"a": ("x", a), "b": (("y", "z"), b)}) diff --git a/doc/internals/extending-xarray.rst b/doc/internals/extending-xarray.rst new file mode 100644 index 00000000000..ef26f30689e --- /dev/null +++ b/doc/internals/extending-xarray.rst @@ -0,0 +1,103 @@ + +Extending xarray +================ + +.. ipython:: python + :suppress: + + import xarray as xr + + +xarray is designed as a general purpose library, and hence tries to avoid +including overly domain specific functionality. But inevitably, the need for more +domain specific logic arises. + +One standard solution to this problem is to subclass Dataset and/or DataArray to +add domain specific functionality. However, inheritance is not very robust. It's +easy to inadvertently use internal APIs when subclassing, which means that your +code may break when xarray upgrades. Furthermore, many builtin methods will +only return native xarray objects. + +The standard advice is to use `composition over inheritance`__, but +reimplementing an API as large as xarray's on your own objects can be an onerous +task, even if most methods are only forwarding to xarray implementations. + +__ https://github.com/pydata/xarray/issues/706 + +If you simply want the ability to call a function with the syntax of a +method call, then the builtin :py:meth:`~xarray.DataArray.pipe` method (copied +from pandas) may suffice. + +To resolve this issue for more complex cases, xarray has the +:py:func:`~xarray.register_dataset_accessor` and +:py:func:`~xarray.register_dataarray_accessor` decorators for adding custom +"accessors" on xarray objects. Here's how you might use these decorators to +write a custom "geo" accessor implementing a geography specific extension to +xarray: + +.. literalinclude:: ../examples/_code/accessor_example.py + +In general, the only restriction on the accessor class is that the ``__init__`` method +must have a single parameter: the ``Dataset`` or ``DataArray`` object it is supposed +to work on. + +This achieves the same result as if the ``Dataset`` class had a cached property +defined that returns an instance of your class: + +.. code-block:: python + + class Dataset: + ... + + @property + def geo(self): + return GeoAccessor(self) + +However, using the register accessor decorators is preferable to simply adding +your own ad-hoc property (i.e., ``Dataset.geo = property(...)``), for several +reasons: + +1. It ensures that the name of your property does not accidentally conflict with + any other attributes or methods (including other accessors). +2. Instances of accessor object will be cached on the xarray object that creates + them. This means you can save state on them (e.g., to cache computed + properties). +3. Using an accessor provides an implicit namespace for your custom + functionality that clearly identifies it as separate from built-in xarray + methods. + +.. note:: + + Accessors are created once per DataArray and Dataset instance. New + instances, like those created from arithmetic operations or when accessing + a DataArray from a Dataset (ex. ``ds[var_name]``), will have new + accessors created. + +Back in an interactive IPython session, we can use these properties: + +.. ipython:: python + :suppress: + + exec(open("examples/_code/accessor_example.py").read()) + +.. ipython:: python + + ds = xr.Dataset({"longitude": np.linspace(0, 10), "latitude": np.linspace(0, 20)}) + ds.geo.center + ds.geo.plot() + +The intent here is that libraries that extend xarray could add such an accessor +to implement subclass specific functionality rather than using actual subclasses +or patching in a large number of domain specific methods. For further reading +on ways to write new accessors and the philosophy behind the approach, see +:issue:`1080`. + +To help users keep things straight, please `let us know +`_ if you plan to write a new accessor +for an open source library. In the future, we will maintain a list of accessors +and the libraries that implement them on this page. + +To make documenting accessors with ``sphinx`` and ``sphinx.ext.autosummary`` +easier, you can use `sphinx-autosummary-accessors`_. + +.. _sphinx-autosummary-accessors: https://sphinx-autosummary-accessors.readthedocs.io/ diff --git a/doc/internals.rst b/doc/internals/how-to-add-new-backend.rst similarity index 63% rename from doc/internals.rst rename to doc/internals/how-to-add-new-backend.rst index f94371731de..a1a838ef5de 100644 --- a/doc/internals.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -1,254 +1,3 @@ -.. _internals: - -xarray Internals -================ - -.. currentmodule:: xarray - -xarray builds upon two of the foundational libraries of the scientific Python -stack, NumPy and pandas. It is written in pure Python (no C or Cython -extensions), which makes it easy to develop and extend. Instead, we push -compiled code to :ref:`optional dependencies`. - -.. ipython:: python - :suppress: - - import dask.array as da - import numpy as np - import pandas as pd - import sparse - import xarray as xr - - np.random.seed(123456) - -Variable objects ----------------- - -The core internal data structure in xarray is the :py:class:`~xarray.Variable`, -which is used as the basic building block behind xarray's -:py:class:`~xarray.Dataset` and :py:class:`~xarray.DataArray` types. A -``Variable`` consists of: - -- ``dims``: A tuple of dimension names. -- ``data``: The N-dimensional array (typically, a NumPy or Dask array) storing - the Variable's data. It must have the same number of dimensions as the length - of ``dims``. -- ``attrs``: An ordered dictionary of metadata associated with this array. By - convention, xarray's built-in operations never use this metadata. -- ``encoding``: Another ordered dictionary used to store information about how - these variable's data is represented on disk. See :ref:`io.encoding` for more - details. - -``Variable`` has an interface similar to NumPy arrays, but extended to make use -of named dimensions. For example, it uses ``dim`` in preference to an ``axis`` -argument for methods like ``mean``, and supports :ref:`compute.broadcasting`. - -However, unlike ``Dataset`` and ``DataArray``, the basic ``Variable`` does not -include coordinate labels along each axis. - -``Variable`` is public API, but because of its incomplete support for labeled -data, it is mostly intended for advanced uses, such as in xarray itself or for -writing new backends. You can access the variable objects that correspond to -xarray objects via the (readonly) :py:attr:`Dataset.variables -` and -:py:attr:`DataArray.variable ` attributes. - - -.. _internals.duck_arrays: - -Integrating with duck arrays ----------------------------- - -.. warning:: - - This is a experimental feature. - -xarray can wrap custom :term:`duck array` objects as long as they define numpy's -``shape``, ``dtype`` and ``ndim`` properties and the ``__array__``, -``__array_ufunc__`` and ``__array_function__`` methods. - -In certain situations (e.g. when printing the collapsed preview of -variables of a ``Dataset``), xarray will display the repr of a :term:`duck array` -in a single line, truncating it to a certain number of characters. If that -would drop too much information, the :term:`duck array` may define a -``_repr_inline_`` method that takes ``max_width`` (number of characters) as an -argument: - -.. code:: python - - class MyDuckArray: - ... - - def _repr_inline_(self, max_width): - """ format to a single line with at most max_width characters """ - ... - - ... - -To avoid duplicated information, this method must omit information about the shape and -:term:`dtype`. For example, the string representation of a ``dask`` array or a -``sparse`` matrix would be: - -.. ipython:: python - - a = da.linspace(0, 1, 20, chunks=2) - a - - b = np.eye(10) - b[[5, 7, 3, 0], [6, 8, 2, 9]] = 2 - b = sparse.COO.from_numpy(b) - b - - xr.Dataset({"a": ("x", a), "b": (("y", "z"), b)}) - -Extending xarray ----------------- - -xarray is designed as a general purpose library, and hence tries to avoid -including overly domain specific functionality. But inevitably, the need for more -domain specific logic arises. - -One standard solution to this problem is to subclass Dataset and/or DataArray to -add domain specific functionality. However, inheritance is not very robust. It's -easy to inadvertently use internal APIs when subclassing, which means that your -code may break when xarray upgrades. Furthermore, many builtin methods will -only return native xarray objects. - -The standard advice is to use `composition over inheritance`__, but -reimplementing an API as large as xarray's on your own objects can be an onerous -task, even if most methods are only forwarding to xarray implementations. - -__ https://github.com/pydata/xarray/issues/706 - -If you simply want the ability to call a function with the syntax of a -method call, then the builtin :py:meth:`~xarray.DataArray.pipe` method (copied -from pandas) may suffice. - -To resolve this issue for more complex cases, xarray has the -:py:func:`~xarray.register_dataset_accessor` and -:py:func:`~xarray.register_dataarray_accessor` decorators for adding custom -"accessors" on xarray objects. Here's how you might use these decorators to -write a custom "geo" accessor implementing a geography specific extension to -xarray: - -.. literalinclude:: examples/_code/accessor_example.py - -In general, the only restriction on the accessor class is that the ``__init__`` method -must have a single parameter: the ``Dataset`` or ``DataArray`` object it is supposed -to work on. - -This achieves the same result as if the ``Dataset`` class had a cached property -defined that returns an instance of your class: - -.. code-block:: python - - class Dataset: - ... - - @property - def geo(self): - return GeoAccessor(self) - -However, using the register accessor decorators is preferable to simply adding -your own ad-hoc property (i.e., ``Dataset.geo = property(...)``), for several -reasons: - -1. It ensures that the name of your property does not accidentally conflict with - any other attributes or methods (including other accessors). -2. Instances of accessor object will be cached on the xarray object that creates - them. This means you can save state on them (e.g., to cache computed - properties). -3. Using an accessor provides an implicit namespace for your custom - functionality that clearly identifies it as separate from built-in xarray - methods. - -.. note:: - - Accessors are created once per DataArray and Dataset instance. New - instances, like those created from arithmetic operations or when accessing - a DataArray from a Dataset (ex. ``ds[var_name]``), will have new - accessors created. - -Back in an interactive IPython session, we can use these properties: - -.. ipython:: python - :suppress: - - exec(open("examples/_code/accessor_example.py").read()) - -.. ipython:: python - - ds = xr.Dataset({"longitude": np.linspace(0, 10), "latitude": np.linspace(0, 20)}) - ds.geo.center - ds.geo.plot() - -The intent here is that libraries that extend xarray could add such an accessor -to implement subclass specific functionality rather than using actual subclasses -or patching in a large number of domain specific methods. For further reading -on ways to write new accessors and the philosophy behind the approach, see -:issue:`1080`. - -To help users keep things straight, please `let us know -`_ if you plan to write a new accessor -for an open source library. In the future, we will maintain a list of accessors -and the libraries that implement them on this page. - -To make documenting accessors with ``sphinx`` and ``sphinx.ext.autosummary`` -easier, you can use `sphinx-autosummary-accessors`_. - -.. _sphinx-autosummary-accessors: https://sphinx-autosummary-accessors.readthedocs.io/ - -.. _zarr_encoding: - -Zarr Encoding Specification ---------------------------- - -In implementing support for the `Zarr `_ storage -format, Xarray developers made some *ad hoc* choices about how to store -NetCDF data in Zarr. -Future versions of the Zarr spec will likely include a more formal convention -for the storage of the NetCDF data model in Zarr; see -`Zarr spec repo `_ for ongoing -discussion. - -First, Xarray can only read and write Zarr groups. There is currently no support -for reading / writting individual Zarr arrays. Zarr groups are mapped to -Xarray ``Dataset`` objects. - -Second, from Xarray's point of view, the key difference between -NetCDF and Zarr is that all NetCDF arrays have *dimension names* while Zarr -arrays do not. Therefore, in order to store NetCDF data in Zarr, Xarray must -somehow encode and decode the name of each array's dimensions. - -To accomplish this, Xarray developers decided to define a special Zarr array -attribute: ``_ARRAY_DIMENSIONS``. The value of this attribute is a list of -dimension names (strings), for example ``["time", "lon", "lat"]``. When writing -data to Zarr, Xarray sets this attribute on all variables based on the variable -dimensions. When reading a Zarr group, Xarray looks for this attribute on all -arrays, raising an error if it can't be found. The attribute is used to define -the variable dimension names and then removed from the attributes dictionary -returned to the user. - -Because of these choices, Xarray cannot read arbitrary array data, but only -Zarr data with valid ``_ARRAY_DIMENSIONS`` attributes on each array. - -After decoding the ``_ARRAY_DIMENSIONS`` attribute and assigning the variable -dimensions, Xarray proceeds to [optionally] decode each variable using its -standard CF decoding machinery used for NetCDF data (see :py:func:`decode_cf`). - -As a concrete example, here we write a tutorial dataset to Zarr and then -re-open it directly with Zarr: - -.. ipython:: python - - ds = xr.tutorial.load_dataset("rasm") - ds.to_zarr("rasm.zarr", mode="w") - import zarr - - zgroup = zarr.open("rasm.zarr") - print(zgroup.tree()) - dict(zgroup["Tair"].attrs) - .. _add_a_backend: How to add a new backend diff --git a/doc/internals/index.rst b/doc/internals/index.rst new file mode 100644 index 00000000000..8cedc67327e --- /dev/null +++ b/doc/internals/index.rst @@ -0,0 +1,20 @@ +.. _internals: + +xarray Internals +================ + +xarray builds upon two of the foundational libraries of the scientific Python +stack, NumPy and pandas. It is written in pure Python (no C or Cython +extensions), which makes it easy to develop and extend. Instead, we push +compiled code to :ref:`optional dependencies`. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + variable-objects + duck-arrays-integration + extending-xarray + zarr-encoding-spec + how-to-add-new-backend diff --git a/doc/internals/variable-objects.rst b/doc/internals/variable-objects.rst new file mode 100644 index 00000000000..6ae3c2f7e6d --- /dev/null +++ b/doc/internals/variable-objects.rst @@ -0,0 +1,31 @@ +Variable objects +================ + +The core internal data structure in xarray is the :py:class:`~xarray.Variable`, +which is used as the basic building block behind xarray's +:py:class:`~xarray.Dataset` and :py:class:`~xarray.DataArray` types. A +``Variable`` consists of: + +- ``dims``: A tuple of dimension names. +- ``data``: The N-dimensional array (typically, a NumPy or Dask array) storing + the Variable's data. It must have the same number of dimensions as the length + of ``dims``. +- ``attrs``: An ordered dictionary of metadata associated with this array. By + convention, xarray's built-in operations never use this metadata. +- ``encoding``: Another ordered dictionary used to store information about how + these variable's data is represented on disk. See :ref:`io.encoding` for more + details. + +``Variable`` has an interface similar to NumPy arrays, but extended to make use +of named dimensions. For example, it uses ``dim`` in preference to an ``axis`` +argument for methods like ``mean``, and supports :ref:`compute.broadcasting`. + +However, unlike ``Dataset`` and ``DataArray``, the basic ``Variable`` does not +include coordinate labels along each axis. + +``Variable`` is public API, but because of its incomplete support for labeled +data, it is mostly intended for advanced uses, such as in xarray itself or for +writing new backends. You can access the variable objects that correspond to +xarray objects via the (readonly) :py:attr:`Dataset.variables +` and +:py:attr:`DataArray.variable ` attributes. diff --git a/doc/internals/zarr-encoding-spec.rst b/doc/internals/zarr-encoding-spec.rst new file mode 100644 index 00000000000..aea75155e80 --- /dev/null +++ b/doc/internals/zarr-encoding-spec.rst @@ -0,0 +1,53 @@ + +.. _zarr_encoding: + +Zarr Encoding Specification +============================ + +In implementing support for the `Zarr `_ storage +format, Xarray developers made some *ad hoc* choices about how to store +NetCDF data in Zarr. +Future versions of the Zarr spec will likely include a more formal convention +for the storage of the NetCDF data model in Zarr; see +`Zarr spec repo `_ for ongoing +discussion. + +First, Xarray can only read and write Zarr groups. There is currently no support +for reading / writting individual Zarr arrays. Zarr groups are mapped to +Xarray ``Dataset`` objects. + +Second, from Xarray's point of view, the key difference between +NetCDF and Zarr is that all NetCDF arrays have *dimension names* while Zarr +arrays do not. Therefore, in order to store NetCDF data in Zarr, Xarray must +somehow encode and decode the name of each array's dimensions. + +To accomplish this, Xarray developers decided to define a special Zarr array +attribute: ``_ARRAY_DIMENSIONS``. The value of this attribute is a list of +dimension names (strings), for example ``["time", "lon", "lat"]``. When writing +data to Zarr, Xarray sets this attribute on all variables based on the variable +dimensions. When reading a Zarr group, Xarray looks for this attribute on all +arrays, raising an error if it can't be found. The attribute is used to define +the variable dimension names and then removed from the attributes dictionary +returned to the user. + +Because of these choices, Xarray cannot read arbitrary array data, but only +Zarr data with valid ``_ARRAY_DIMENSIONS`` attributes on each array. + +After decoding the ``_ARRAY_DIMENSIONS`` attribute and assigning the variable +dimensions, Xarray proceeds to [optionally] decode each variable using its +standard CF decoding machinery used for NetCDF data (see :py:func:`decode_cf`). + +As a concrete example, here we write a tutorial dataset to Zarr and then +re-open it directly with Zarr: + +.. ipython:: python + + import xarray as xr + import zarr + + ds = xr.tutorial.load_dataset("rasm") + ds.to_zarr("rasm.zarr", mode="w") + + zgroup = zarr.open("rasm.zarr") + print(zgroup.tree()) + dict(zgroup["Tair"].attrs) diff --git a/doc/roadmap.rst b/doc/roadmap.rst index 1cbbaf8ef42..dd5235bfb16 100644 --- a/doc/roadmap.rst +++ b/doc/roadmap.rst @@ -206,27 +206,10 @@ In order to lower this adoption barrier, we propose to: - Write a basic glossary that defines terms that might not be familiar to all (e.g. "lazy", "labeled", "serialization", "indexing", "backend"). + Administrative -------------- -Current core developers -~~~~~~~~~~~~~~~~~~~~~~~ - -- Stephan Hoyer -- Ryan Abernathey -- Joe Hamman -- Benoit Bovy -- Fabien Maussion -- Keisuke Fujii -- Maximilian Roos -- Deepak Cherian -- Spencer Clark -- Tom Nicholas -- Guido Imperiale -- Justus Magin -- Mathias Hauser -- Anderson Banihirwe - NumFOCUS ~~~~~~~~ diff --git a/doc/team.rst b/doc/team.rst new file mode 100644 index 00000000000..7b185dc3a52 --- /dev/null +++ b/doc/team.rst @@ -0,0 +1,87 @@ +Team +----- + +Current core developers +~~~~~~~~~~~~~~~~~~~~~~~ + +Xarray core developers are responsible for the ongoing organizational maintenance and technical direction of the xarray project. + +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` + + + +The full list of contributors is on our `GitHub Contributors Page `__. diff --git a/doc/tutorials-and-videos.rst b/doc/tutorials-and-videos.rst new file mode 100644 index 00000000000..6189fb745db --- /dev/null +++ b/doc/tutorials-and-videos.rst @@ -0,0 +1,64 @@ + +Tutorials and Videos +==================== + + +Tutorials +---------- + +- `Xarray's Tutorials`_ repository +- The `UW eScience Institute's Geohackweek`_ tutorial on xarray for geospatial data scientists. +- `Nicolas Fauchereau's 2015 tutorial`_ on xarray for netCDF users. + + + +Videos +------- + +.. panels:: + :card: text-center + + --- + + 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 +----------------------------- + +- Stephan Hoyer and Joe Hamman's `Journal of Open Research Software paper`_ describing the xarray project. + + +.. _Xarray's Tutorials: https://xarray-contrib.github.io/xarray-tutorial/ +.. _Journal of Open Research Software paper: http://doi.org/10.5334/jors.148 +.. _UW eScience Institute's Geohackweek : https://geohackweek.github.io/nDarrays/ +.. _tutorial: https://github.com/Unidata/unidata-users-workshop/blob/master/notebooks/xray-tutorial.ipynb +.. _with answers: https://github.com/Unidata/unidata-users-workshop/blob/master/notebooks/xray-tutorial-with-answers.ipynb +.. _Nicolas Fauchereau's 2015 tutorial: http://nbviewer.iPython.org/github/nicolasfauchereau/metocean/blob/master/notebooks/xray.ipynb diff --git a/doc/combining.rst b/doc/user-guide/combining.rst similarity index 100% rename from doc/combining.rst rename to doc/user-guide/combining.rst diff --git a/doc/computation.rst b/doc/user-guide/computation.rst similarity index 99% rename from doc/computation.rst rename to doc/user-guide/computation.rst index dcfe270a942..28804bcba6f 100644 --- a/doc/computation.rst +++ b/doc/user-guide/computation.rst @@ -6,6 +6,7 @@ Computation ########### + The labels associated with :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects enables some powerful shortcuts for computation, notably including aggregation and broadcasting by dimension diff --git a/doc/dask.rst b/doc/user-guide/dask.rst similarity index 99% rename from doc/dask.rst rename to doc/user-guide/dask.rst index 4844967350b..e92aacbe511 100644 --- a/doc/dask.rst +++ b/doc/user-guide/dask.rst @@ -21,7 +21,7 @@ and at the `Dask examples website `_. What is a Dask array? --------------------- -.. image:: _static/dask_array.png +.. image:: ../_static/dask_array.png :width: 40 % :align: right :alt: A Dask array diff --git a/doc/data-structures.rst b/doc/user-guide/data-structures.rst similarity index 99% rename from doc/data-structures.rst rename to doc/user-guide/data-structures.rst index ac78e1769d5..14881e0c261 100644 --- a/doc/data-structures.rst +++ b/doc/user-guide/data-structures.rst @@ -251,7 +251,7 @@ quantities that belong in data. Here is an example of how we might structure a dataset for a weather forecast: -.. image:: _static/dataset-diagram.png +.. image:: ../_static/dataset-diagram.png In this example, it would be natural to call ``temperature`` and ``precipitation`` "data variables" and all the other arrays "coordinate diff --git a/doc/duckarrays.rst b/doc/user-guide/duckarrays.rst similarity index 100% rename from doc/duckarrays.rst rename to doc/user-guide/duckarrays.rst diff --git a/doc/groupby.rst b/doc/user-guide/groupby.rst similarity index 100% rename from doc/groupby.rst rename to doc/user-guide/groupby.rst diff --git a/doc/user-guide/index.rst b/doc/user-guide/index.rst new file mode 100644 index 00000000000..edeb0aac632 --- /dev/null +++ b/doc/user-guide/index.rst @@ -0,0 +1,27 @@ +########### +User Guide +########### + +In this user guide, you will find detailed descriptions and +examples that describe many common tasks that you can accomplish with xarray. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + terminology + data-structures + indexing + interpolation + computation + groupby + reshaping + combining + time-series + weather-climate + pandas + io + dask + plotting + duckarrays diff --git a/doc/indexing.rst b/doc/user-guide/indexing.rst similarity index 100% rename from doc/indexing.rst rename to doc/user-guide/indexing.rst diff --git a/doc/interpolation.rst b/doc/user-guide/interpolation.rst similarity index 99% rename from doc/interpolation.rst rename to doc/user-guide/interpolation.rst index 9a3b7a7ee2d..8a7f9ebe911 100644 --- a/doc/interpolation.rst +++ b/doc/user-guide/interpolation.rst @@ -179,7 +179,7 @@ For example, if you want to interpolate a two dimensional array along a particul you can pass two 1-dimensional :py:class:`~xarray.DataArray` s with a common dimension as new coordinate. -.. image:: _static/advanced_selection_interpolation.svg +.. image:: ../_static/advanced_selection_interpolation.svg :height: 200px :width: 400 px :alt: advanced indexing and interpolation diff --git a/doc/io.rst b/doc/user-guide/io.rst similarity index 99% rename from doc/io.rst rename to doc/user-guide/io.rst index c2022cc9325..41cb53e4d6b 100644 --- a/doc/io.rst +++ b/doc/user-guide/io.rst @@ -621,7 +621,7 @@ over the network until we look at particular values: # the data is downloaded automatically when we make the plot In [6]: tmax[0].plot() -.. image:: _static/opendap-prism-tmax.png +.. image:: ../_static/opendap-prism-tmax.png Some servers require authentication before we can access the data. For this purpose we can explicitly create a :py:class:`backends.PydapDataStore` diff --git a/doc/pandas.rst b/doc/user-guide/pandas.rst similarity index 100% rename from doc/pandas.rst rename to doc/user-guide/pandas.rst diff --git a/doc/plotting.rst b/doc/user-guide/plotting.rst similarity index 100% rename from doc/plotting.rst rename to doc/user-guide/plotting.rst diff --git a/doc/reshaping.rst b/doc/user-guide/reshaping.rst similarity index 100% rename from doc/reshaping.rst rename to doc/user-guide/reshaping.rst diff --git a/doc/terminology.rst b/doc/user-guide/terminology.rst similarity index 98% rename from doc/terminology.rst rename to doc/user-guide/terminology.rst index 3cfc211593f..1876058323e 100644 --- a/doc/terminology.rst +++ b/doc/user-guide/terminology.rst @@ -79,7 +79,7 @@ complete examples, please consult the relevant documentation.* example, multidimensional coordinates are often used in geoscience datasets when :doc:`the data's physical coordinates (such as latitude and longitude) differ from their logical coordinates - `. However, non-dimension coordinates + <../examples/multidimensional-coords>`. However, non-dimension coordinates are not indexed, and any operation on non-dimension coordinates that leverages indexing will fail. Printing ``arr.coords`` will print all of ``arr``'s coordinate names, with the corresponding dimension(s) in diff --git a/doc/time-series.rst b/doc/user-guide/time-series.rst similarity index 99% rename from doc/time-series.rst rename to doc/user-guide/time-series.rst index 96a2edc0ea5..f9d341ff25d 100644 --- a/doc/time-series.rst +++ b/doc/user-guide/time-series.rst @@ -224,4 +224,4 @@ Data that has indices outside of the given ``tolerance`` are set to ``NaN``. For more examples of using grouped operations on a time dimension, see -:doc:`examples/weather-data`. +:doc:`../examples/weather-data`. diff --git a/doc/weather-climate.rst b/doc/user-guide/weather-climate.rst similarity index 99% rename from doc/weather-climate.rst rename to doc/user-guide/weather-climate.rst index 068edba1e64..e14b77386b2 100644 --- a/doc/weather-climate.rst +++ b/doc/user-guide/weather-climate.rst @@ -8,7 +8,7 @@ Weather and climate data import xarray as xr -``xarray`` can leverage metadata that follows the `Climate and Forecast (CF) conventions`_ if present. Examples include automatic labelling of plots with descriptive names and units if proper metadata is present (see :ref:`plotting`) and support for non-standard calendars used in climate science through the ``cftime`` module (see :ref:`CFTimeIndex`). There are also a number of geosciences-focused projects that build on xarray (see :ref:`related-projects`). +``xarray`` can leverage metadata that follows the `Climate and Forecast (CF) conventions`_ if present. Examples include automatic labelling of plots with descriptive names and units if proper metadata is present (see :ref:`plotting`) and support for non-standard calendars used in climate science through the ``cftime`` module (see :ref:`CFTimeIndex`). There are also a number of geosciences-focused projects that build on xarray (see :ref:`ecosystem`). .. _Climate and Forecast (CF) conventions: http://cfconventions.org diff --git a/doc/whats-new.rst b/doc/whats-new.rst index c7fba22e4ad..e58f80cfcd3 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -84,6 +84,8 @@ Documentation the docstrings of :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` (:issue:`5016`, :pull:`5020`). By `Aaron Spring `_. +- New sphinx theme & rearrangement of the docs (:pull:`4835`). + By `Anderson Banihirwe `_. Internal Changes ~~~~~~~~~~~~~~~~ @@ -111,6 +113,7 @@ Breaking changes ~~~~~~~~~~~~~~~~ - xarray no longer supports python 3.6 + The minimum versions of some other dependencies were changed: The minimum version policy was changed to also apply to projects with irregular releases. As a result, the minimum versions of some dependencies have changed: @@ -513,7 +516,7 @@ New Features By `Aaron Spring `_. - Use a wrapped array's ``_repr_inline_`` method to construct the collapsed ``repr`` of :py:class:`DataArray` and :py:class:`Dataset` objects and - document the new method in :doc:`internals`. (:pull:`4248`). + document the new method in :doc:`internals/index`. (:pull:`4248`). By `Justus Magin `_. - Allow per-variable fill values in most functions. (:pull:`4237`). By `Justus Magin `_. @@ -2516,7 +2519,7 @@ non-standard calendars used in climate modeling. Documentation ~~~~~~~~~~~~~ -- New FAQ entry, :ref:`related-projects`. +- New FAQ entry, :ref:`ecosystem`. By `Deepak Cherian `_. - :ref:`assigning_values` now includes examples on how to select and assign values to a :py:class:`~xarray.DataArray` with ``.loc``. @@ -4561,11 +4564,11 @@ Highlights ~~~~~~~~~~ The headline feature in this release is experimental support for out-of-core -computing (data that doesn't fit into memory) with dask_. This includes a new +computing (data that doesn't fit into memory) with :doc:`user-guide/dask`. This includes a new top-level function ``xray.open_mfdataset`` that makes it easy to open a collection of netCDF (using dask) as a single ``xray.Dataset`` object. For more on dask, read the `blog post introducing xray + dask`_ and the new -documentation section :doc:`dask`. +documentation section :doc:`user-guide/dask`. .. _blog post introducing xray + dask: https://www.anaconda.com/blog/developer-blog/xray-dask-out-core-labeled-arrays-python/