From 56209bd9a3192e4f1e82c21e5ffcf4c3bacaaae3 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Mon, 24 Jun 2024 11:31:30 -0400 Subject: [PATCH] Docs: Add page with figure for navigating help resources (#9147) * add config to build mermaid diagrams in docs --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Deepak Cherian --- ci/requirements/doc.yml | 1 + doc/conf.py | 5 +++ doc/help-diagram.rst | 75 +++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 4 ++- doc/whats-new.rst | 3 ++ 5 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 doc/help-diagram.rst 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 ~~~~~~~~~~~~~~~~