Skip to content

Docs: Add figure for navigating help resources #9147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jun 24, 2024
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ci/requirements/doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 ../..
3 changes: 3 additions & 0 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,10 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.

# sphinxcontrib.mermaid should go first or the diagram will not render (https://github.com/mgaitan/sphinxcontrib-mermaid/issues/124)
extensions = [
"sphinxcontrib.mermaid",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
Expand Down
75 changes: 75 additions & 0 deletions doc/getting-started-guide/help-diagram.rst
Original file line number Diff line number Diff line change
@@ -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 <https://tutorial.xarray.dev/>`__
- `Xarray Docs <https://docs.xarray.dev/en/stable/>`__
- `Google/Stack Exchange <https://stackoverflow.com/questions/tagged/python-xarray>`__
- `Xarray Discussions <https://github.com/pydata/xarray/discussions>`__
- `Xarray Discord <https://discord.com/invite/wEKPCt4PDu>`__
- `Xarray Office Hours <https://github.com/pydata/xarray/discussions/categories/office-hours>`__
- `Pangeo Discourse <https://discourse.pangeo.io/>`__
- `Xarray Issues <https://github.com/pydata/xarray/issues>`__
- `Xarray Contributors Guide <https://docs.xarray.dev/en/stable/contributing.html>`__
- `Developer's Meeting <https://docs.xarray.dev/en/stable/developers-meeting.html>`__
1 change: 1 addition & 0 deletions doc/getting-started-guide/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ It is designed as an entry point for new users, and it provided an introduction
installing
quick-overview
faq
help-diagram
3 changes: 2 additions & 1 deletion doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ efficient, and fun!
`Releases <https://github.com/pydata/xarray/releases>`__ |
`Stack Overflow <https://stackoverflow.com/questions/tagged/python-xarray>`__ |
`Mailing List <https://groups.google.com/g/xarray>`__ |
`Blog <https://xarray.dev/blog>`__
`Blog <https://xarray.dev/blog>`__ |
`Tutorials <https://tutorial.xarray.dev/>`__


.. grid:: 1 1 2 2
Expand Down
3 changes: 2 additions & 1 deletion doc/whats-new.rst
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ Bug fixes

Documentation
~~~~~~~~~~~~~

- Adds a flow-chart diagram to help users navigate help resources (`Discussion #8990 <https://github.com/pydata/xarray/discussions/8990>`_).
By `Jessica Scheick <https://github.com/jessicas11>`_.

Internal Changes
~~~~~~~~~~~~~~~~
Expand Down
Loading