Skip to content

Commit 59e98f1

Browse files
scottyhqkmuehlbauer
scottyhq
and
kmuehlbauer
authored
Docs: Add links to getting help mermaid diagram (pydata#10324)
* add links to mermaid diagram, fix docs version string * try theme colors * fix for icon color * separate google and stack exchange * custom link colors * keep links for accessibility * links to subsection pages --------- Co-authored-by: Kai Mühlbauer <kai.muehlbauer@uni-bonn.de>
1 parent ba27c6a commit 59e98f1

File tree

2 files changed

+61
-47
lines changed

2 files changed

+61
-47
lines changed

‎doc/conf.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
import sys
77
from contextlib import suppress
88
from textwrap import dedent, indent
9-
9+
import packaging.version
1010
import sphinx_autosummary_accessors
1111
import yaml
1212
from sphinx.application import Sphinx
@@ -185,7 +185,7 @@
185185
autodoc_type_aliases = napoleon_type_aliases # Keep both in sync
186186

187187
# mermaid config
188-
mermaid_version = "10.9.1"
188+
mermaid_version = "11.6.0"
189189

190190
# Add any paths that contain templates here, relative to this directory.
191191
templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
@@ -201,10 +201,9 @@
201201
project = "xarray"
202202
copyright = f"2014-{datetime.datetime.now().year}, xarray Developers"
203203

204-
# The short X.Y version.
205-
version = xarray.__version__.split("+")[0]
206-
# The full version, including alpha/beta/rc tags.
207-
release = xarray.__version__
204+
# The short Y.M.D version.
205+
v = packaging.version.parse(xarray.__version__)
206+
version = ".".join(str(p) for p in v.release)
208207

209208
# There are two options for replacing |today|: either, you set today to some
210209
# non-false value, then it is used:
@@ -314,6 +313,7 @@
314313
"installing.rst": "getting-started-guide/installing.rst",
315314
"quick-overview.rst": "getting-started-guide/quick-overview.rst",
316315
"contributing.rst": "contribute/contributing.rst",
316+
"developers-meeting.rst": "contribute/developers-meeting.rst",
317317
}
318318

319319
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

‎doc/get-help/help-diagram.rst

Lines changed: 55 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -3,53 +3,72 @@ Getting Help
33

44
Navigating the wealth of resources available for Xarray can be overwhelming.
55
We've created this flow chart to help guide you towards the best way to get help, depending on what you're working towards.
6-
The links to each resource are provided below the diagram.
76

8-
Also be sure to check out our "FAQ" and "How do I..." pages in this section for solutions to common questions.
7+
Also be sure to check out our :ref:`faq`. and :ref:`howdoi` pages for solutions to common questions.
98

10-
A major strength of Xarray is in the user community. Sometimes you might not have a concrete question by would simply like to connect with other Xarray users. We have a few
9+
A major strength of Xarray is in the user community. Sometimes you might not yet have a concrete question but would simply like to connect with other Xarray users. We have a few accounts on different social platforms for that! :ref:`socials`.
1110

1211
We look forward to hearing from you!
1312

13+
Help Flowchart
14+
--------------
15+
..
16+
_comment: mermaid Flowcharg "link" text gets secondary color background, SVG icon fill gets primary color
17+
18+
.. raw:: html
19+
20+
<style>
21+
/* Ensure PST link colors don't override mermaid text colors */
22+
.mermaid a {
23+
color: white;
24+
}
25+
.mermaid a:hover {
26+
color: magenta;
27+
text-decoration-color: magenta;
28+
}
29+
.mermaid a:visited {
30+
color: white;
31+
text-decoration-color: white;
32+
}
33+
</style>
34+
1435
.. mermaid::
36+
:config: {"theme":"base","themeVariables":{"fontSize":"20px","primaryColor":"#fff","primaryTextColor":"#fff","primaryBorderColor":"#59c7d6","lineColor":"#e28126","secondaryColor":"#767985"}}
1537
:alt: Flowchart illustrating the different ways to access help using or contributing to Xarray.
1638

1739
flowchart TD
1840
intro[Welcome to Xarray! How can we help?]:::quesNodefmt
19-
usage(["fa:fa-chalkboard-user Xarray Tutorials
20-
fab:fa-readme Xarray Docs
21-
fab:fa-google Google/fab:fa-stack-overflow Stack Exchange
22-
fa:fa-robot Ask AI/a Language Learning Model (LLM)"]):::ansNodefmt
23-
API([fab:fa-readme Xarray Docs
24-
fab:fa-readme extension's docs]):::ansNodefmt
25-
help([fab:fa-github Xarray Discussions
26-
fab:fa-discord Xarray Discord
27-
fa:fa-users Xarray Office Hours
28-
fa:fa-globe Pangeo Discourse]):::ansNodefmt
29-
bug([Report and Propose here:
30-
fab:fa-github Xarray Issues]):::ansNodefmt
31-
contrib([fa:fa-book-open Xarray Contributor's Guide]):::ansNodefmt
32-
pr(["fab:fa-github Pull Request (PR)"]):::ansNodefmt
33-
dev([fab:fa-github Comment on your PR
34-
fa:fa-users Developer's Meeting]):::ansNodefmt
41+
usage([fa:fa-chalkboard-user <a href="https://tutorial.xarray.dev">Xarray Tutorial</a>
42+
fab:fa-readme <a href="https://docs.xarray.dev">Xarray Docs</a>
43+
fab:fa-stack-overflow <a href="https://stackoverflow.com/questions/tagged/python-xarray">Stack Exchange</a>
44+
fab:fa-google <a href="https://www.google.com">Ask Google</a>
45+
fa:fa-robot Ask AI ChatBot]):::ansNodefmt
46+
extensions([Extension docs:
47+
fab:fa-readme <a href="https://docs.dask.org">Dask</a>
48+
fab:fa-readme <a href="https://corteva.github.io/rioxarray">Rioxarray</a>]):::ansNodefmt
49+
help([fab:fa-github <a href="https://github.com/pydata/xarray/discussions">Xarray Discussions</a>
50+
fab:fa-discord <a href="https://discord.com/invite/wEKPCt4PDu">Xarray Discord</a>
51+
fa:fa-globe <a href="https://discourse.pangeo.io">Pangeo Discourse</a>]):::ansNodefmt
52+
bug([Let us know:
53+
fab:fa-github <a href="https://github.com/pydata/xarray/issues">Xarray Issues</a>]):::ansNodefmt
54+
contrib([fa:fa-book-open <a href="https://docs.xarray.dev/en/latest/contribute">Xarray Contributor's Guide</a>]):::ansNodefmt
55+
pr([fab:fa-github <a href="https://github.com/pydata/xarray/pulls">Pull Request</a>]):::ansNodefmt
56+
dev([fab:fa-github Add PR Comment
57+
fa:fa-users <a href="https://docs.xarray.dev/en/stable/contribute/developers-meeting.html">Attend Developer's Meeting</a> ]):::ansNodefmt
3558
report[Thanks for letting us know!]:::quesNodefmt
36-
merged[fa:fa-hands-clapping Your PR was merged.
37-
Thanks for contributing to Xarray!]:::quesNodefmt
59+
merged[fa:fa-hands-clapping Thanks for contributing to Xarray!]:::quesNodefmt
3860

3961

4062
intro -->|How do I use Xarray?| usage
41-
usage -->|"with extensions (like Dask)"| API
63+
usage -->|"With extensions (like Dask, Rioxarray, etc.)"| extensions
4264

43-
usage -->|I'd like some more help| help
44-
intro -->|I found a bug| bug
45-
intro -->|I'd like to make a small change| contrib
46-
subgraph bugcontrib[Bugs and Contributions]
47-
bug
48-
contrib
49-
bug -->|I just wanted to tell you| report
50-
bug<-->|I'd like to fix the bug!| contrib
51-
pr -->|my PR was approved| merged
52-
end
65+
usage -->|I still have questions or could use some guidance | help
66+
intro -->|I think I found a bug| bug
67+
bug
68+
contrib
69+
bug -->|I just wanted to tell you| report
70+
bug<-->|I'd like to fix the bug!| contrib
71+
pr -->|my PR was approved| merged
5372

5473

5574
intro -->|I wish Xarray could...| bug
@@ -58,20 +77,16 @@ We look forward to hearing from you!
5877
pr <-->|my PR is quiet| dev
5978
contrib -->pr
6079

61-
classDef quesNodefmt fill:#9DEEF4,stroke:#206C89
62-
63-
classDef ansNodefmt fill:#FFAA05,stroke:#E37F17
80+
classDef quesNodefmt font-size:20pt,fill:#0e4666,stroke:#59c7d6,stroke-width:3
81+
classDef ansNodefmt font-size:18pt,fill:#4a4a4a,stroke:#17afb4,stroke-width:3
82+
linkStyle default font-size:16pt,stroke-width:4
6483

65-
classDef boxfmt fill:#FFF5ED,stroke:#E37F17
66-
class bugcontrib boxfmt
67-
68-
linkStyle default font-size:20pt,color:#206C89
6984

7085
Flowchart links
7186
---------------
7287
- `Xarray Tutorials <https://tutorial.xarray.dev/>`__
7388
- `Xarray Docs <https://docs.xarray.dev>`__
74-
- `Google/Stack Exchange <https://stackoverflow.com/questions/tagged/python-xarray>`__
89+
- `Stack Exchange <https://stackoverflow.com/questions/tagged/python-xarray>`__
7590
- `Xarray Discussions <https://github.com/pydata/xarray/discussions>`__
7691
- `Xarray Discord <https://discord.com/invite/wEKPCt4PDu>`__
7792
- `Xarray Office Hours <https://github.com/pydata/xarray/discussions/categories/office-hours>`__
@@ -80,7 +95,6 @@ Flowchart links
8095
- :ref:`contributing`
8196
- :ref:`developers-meeting`
8297

83-
8498
.. toctree::
8599
:maxdepth: 1
86100
:hidden:

0 commit comments

Comments
 (0)