restructure the contributing guide

doc/contributing.rst

@@ -10,12 +10,25 @@ Contributing to xarray
   Large parts of this document came from the `Pandas Contributing
   Guide <http://pandas.pydata.org/pandas-docs/stable/contributing.html>`_.
 
+We welcome your skills and enthusiasm at the xarray project!. There are numerous opportunities to
+contribute beyond just writing code.
+All contributions, including bug reports, bug fixes, documentation improvements, enhancement suggestions,
+and other ideas are welcome.
+
+If you have any questions on the process or how to fix something feel free to ask us!
+The recommended place to ask a question is  on `GitHub Discussions <https://github.com/pydata/xarray/discussions>`_
+, but we also have a `Discord <https://discord.com/invite/wEKPCt4PDu>`_ and a
+`mailing list <https://groups.google.com/g/xarray>`_. There is also a
+`"python-xarray" tag on Stack Overflow <https://stackoverflow.com/questions/tagged/python-xarray>`_ which we monitor for questions.
+
+We also have a biweekly community call, details of which are announced on the
+`Developers meeting <https://docs.xarray.dev/en/stable/developers-meeting.html>`_.
+You are very welcome to join! Though we would love to hear from you, there is no expectation to
+contribute during the meeting either - you are always welcome to just sit in and listen.
+
 Where to start?
 ===============
 
-All contributions, bug reports, bug fixes, documentation improvements,
-enhancements, and ideas are welcome.
-
 If you are brand new to *xarray* or open-source development, we recommend going
 through the `GitHub "issues" tab <https://github.com/pydata/xarray/issues>`_
 to find issues that interest you. There are a number of issues listed under
@@ -25,9 +38,6 @@ and `good first issue
 where you could start out. Once you've found an interesting issue, you can
 return here to get your development environment setup.
 
-Feel free to ask questions on the `mailing list
-<https://groups.google.com/g/xarray>`_.
-
 .. _contributing.bug_reports:
 
 Bug reports and enhancement requests
@@ -363,6 +373,57 @@ If you want to do a full clean build, do::
     make clean
     make html
 
+Writing ReST pages
+------------------
+
+Most documentation is either in the docstrings of individual classes and methods, in explicit
+``.rst`` files, or in examples and tutorials. All of these use the
+`ReST <https://docutils.sourceforge.io/rst.html>`_ syntax and are processed by
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+This section contains additional information and conventions how ReST is used in the
+xarray documentation.
+
+Section formatting
+~~~~~~~~~~~~~~~~~~
+
+We aim to follow the recommendations from the
+`Python documentation <https://devguide.python.org/documentation/start-documenting/index.html#sections>`_
+and the `Sphinx reStructuredText documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ f
+or section markup characters,
+
+- ``#`` with overline, for parts. This is reserved for the main title in ``index.rst``. All other pages should start with "chapter" or lower.
+
+- ``*`` with overline, for chapters
+
+- ``=``, for sections
+
+- ``-``, for subsections
+
+- ``^``, for subsubsections
+
+- ``"``, for paragraphs
+
+Referring to other documents and sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Sphinx  <https://www.sphinx-doc.org/en/master/>`_ allows internal
+`references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ between documents.
+
+Documents can be linked with the ``:doc:`` directive:
+
+::
+
+    See the :doc:`/getting-started-guide/installing`
+
+    See the tutorial :doc:`/getting-started-guide/quick-overview`
+
+will render as:
+
+    See the `Installation <https://docs.xarray.dev/en/stable/getting-started-guide/installing.html>`_
+
+    See the `Quick Overview <https://docs.xarray.dev/en/stable/getting-started-guide/quick-overview.html>`_
+
 .. _contributing.code:
 
 Contributing to the code base
@@ -491,8 +552,7 @@ Writing tests
 All tests should go into the ``tests`` subdirectory of the specific package.
 This folder contains many current examples of tests, and we suggest looking to these for
 inspiration.  If your test requires working with files or
-network connectivity, there is more information on the `testing page
-<https://github.com/pydata/xarray/wiki/Testing>`_ of the wiki.
+network connectivity.
 
 The ``xarray.testing`` module has many special ``assert`` functions that
 make it easier to make statements about whether DataArray or Dataset objects are
@@ -764,6 +824,9 @@ Contributing your changes to *xarray*
 Committing your code
 --------------------
 
+`Pull requests (PRs) on GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
+are the mechanism for contributing to xarray's code and documentation.
+
 Keep style fixes to a separate commit to make your pull request more readable.
 
 Once you've made changes, you can see them by typing::