diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml
index 066d085ec53..39c2d4d6e88 100644
--- a/ci/requirements/doc.yml
+++ b/ci/requirements/doc.yml
@@ -42,5 +42,6 @@ dependencies:
- sphinxext-rediraffe
- zarr>=2.10
- pip:
+ - sphinxcontrib-mermaid
# relative to this file. Needs to be editable to be accepted.
- -e ../..
diff --git a/doc/conf.py b/doc/conf.py
index 80b24445f71..91bcdf8b8f8 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -59,6 +59,7 @@
)
nbsphinx_allow_errors = False
+nbsphinx_requirejs_path = ""
# -- General configuration ------------------------------------------------
@@ -68,7 +69,9 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
+
extensions = [
+ "sphinxcontrib.mermaid",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
@@ -175,6 +178,8 @@
"pd.NaT": "~pandas.NaT",
}
+# mermaid config
+mermaid_version = "10.9.1"
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
diff --git a/doc/help-diagram.rst b/doc/help-diagram.rst
new file mode 100644
index 00000000000..a42a2f0936a
--- /dev/null
+++ b/doc/help-diagram.rst
@@ -0,0 +1,75 @@
+Getting Help
+============
+
+Navigating the wealth of resources available for Xarray can be overwhelming.
+We've created this flow chart to help guide you towards the best way to get help, depending on what you're working towards.
+The links to each resource are provided below the diagram.
+Regardless of how you interact with us, we're always thrilled to hear from you!
+
+.. mermaid::
+ :alt: Flowchart illustrating the different ways to access help using or contributing to Xarray.
+
+ flowchart TD
+ intro[Welcome to Xarray! How can we help?]:::quesNodefmt
+ usage(["fa:fa-chalkboard-user Xarray Tutorials
+ fab:fa-readme Xarray Docs
+ fab:fa-google Google/fab:fa-stack-overflow Stack Exchange
+ fa:fa-robot Ask AI/a Language Learning Model (LLM)"]):::ansNodefmt
+ API([fab:fa-readme Xarray Docs
+ fab:fa-readme extension's docs]):::ansNodefmt
+ help([fab:fa-github Xarray Discussions
+ fab:fa-discord Xarray Discord
+ fa:fa-users Xarray Office Hours
+ fa:fa-globe Pangeo Discourse]):::ansNodefmt
+ bug([Report and Propose here:
+ fab:fa-github Xarray Issues]):::ansNodefmt
+ contrib([fa:fa-book-open Xarray Contributor's Guide]):::ansNodefmt
+ pr(["fab:fa-github Pull Request (PR)"]):::ansNodefmt
+ dev([fab:fa-github Comment on your PR
+ fa:fa-users Developer's Meeting]):::ansNodefmt
+ report[Thanks for letting us know!]:::quesNodefmt
+ merged[fa:fa-hands-clapping Your PR was merged.
+ Thanks for contributing to Xarray!]:::quesNodefmt
+
+
+ intro -->|How do I use Xarray?| usage
+ usage -->|"with extensions (like Dask)"| API
+
+ usage -->|I'd like some more help| help
+ intro -->|I found a bug| bug
+ intro -->|I'd like to make a small change| contrib
+ subgraph bugcontrib[Bugs and Contributions]
+ bug
+ contrib
+ bug -->|I just wanted to tell you| report
+ bug<-->|I'd like to fix the bug!| contrib
+ pr -->|my PR was approved| merged
+ end
+
+
+ intro -->|I wish Xarray could...| bug
+
+
+ pr <-->|my PR is quiet| dev
+ contrib -->pr
+
+ classDef quesNodefmt fill:#9DEEF4,stroke:#206C89
+
+ classDef ansNodefmt fill:#FFAA05,stroke:#E37F17
+
+ classDef boxfmt fill:#FFF5ED,stroke:#E37F17
+ class bugcontrib boxfmt
+
+ linkStyle default font-size:20pt,color:#206C89
+
+
+- `Xarray Tutorials `__
+- `Xarray Docs `__
+- `Google/Stack Exchange `__
+- `Xarray Discussions `__
+- `Xarray Discord `__
+- `Xarray Office Hours `__
+- `Pangeo Discourse `__
+- `Xarray Issues `__
+- `Xarray Contributors Guide `__
+- `Developer's Meeting `__
diff --git a/doc/index.rst b/doc/index.rst
index 138e9d91601..4a5fe4ee080 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,7 +14,8 @@ efficient, and fun!
`Releases `__ |
`Stack Overflow `__ |
`Mailing List `__ |
-`Blog `__
+`Blog `__ |
+`Tutorials `__
.. grid:: 1 1 2 2
@@ -65,6 +66,7 @@ efficient, and fun!
Tutorials & Videos
API Reference
How do I ...
+ Getting Help
Ecosystem
.. toctree::
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index 51a2c98fb9c..c3383a5648a 100644
--- a/doc/whats-new.rst
+++ b/doc/whats-new.rst
@@ -40,9 +40,12 @@ Bug fixes
Documentation
~~~~~~~~~~~~~
+- Adds a flow-chart diagram to help users navigate help resources (`Discussion #8990 `_).
+ By `Jessica Scheick `_.
- Improvements to Zarr & chunking docs (:pull:`9139`, :pull:`9140`, :pull:`9132`)
By `Maximilian Roos `_
+
Internal Changes
~~~~~~~~~~~~~~~~