Update Contribution types, Reference, and In depth explanations in Contributing guide (#2521)

* Update pages under Contribution types section

* Change version from 1.0.0 to 1.0

* Use 'package' instead of 'subpackage' when refering to arviz-* packages.

* Typo

* Unify TODO

* Remove architecture.md and developing_in_docker.md

* Simplify pull request checklist

* Update pages in 'Reference'

* Update in-depth explanations

* Fix references and add h5py to doc environment

* Restore miniatures to branch base

* Update docs/source/contributing/contributing_prs.md

Co-authored-by: Oriol Abril-Pla <[email protected]>

* Update docs/source/contributing/docstrings.md

Co-authored-by: Oriol Abril-Pla <[email protected]>

* Update docs/source/contributing/contributing_prs.md

Co-authored-by: Oriol Abril-Pla <[email protected]>

* Update docs/source/contributing/diataxis_for_arviz.md

Co-authored-by: Oriol Abril-Pla <[email protected]>

* Incorporate feedback

* run tox check

---------

Co-authored-by: Oriol Abril-Pla <[email protected]>

Author: tomicapretto

docs/source/contributing/architecture.md

@@ -1,6 +1,9 @@
 (content_structure)=
 # Documentation content structure
 
+:::{caution} Some content in this page may be outdated.
+:::
+
 ArviZ documentation has the {doc}`diataxis:index` as a North Star.
 This page assumes basic familiarity with Diátaxis.
 

docs/source/contributing/content_structure.md

@@ -1,10 +1,9 @@
 # Contributing code via pull requests
 
 While issue reporting is valuable, we strongly encourage users who are
-inclined to do so to submit patches for new or existing issues via pull
-requests. This is particularly the case for simple fixes, such as typos
-or tweaks to documentation, which do not require a heavy investment
-of time and attention.
+inclined to do so to submit patches for new or existing issues via pull requests.
+This is particularly the case for simple fixes, such as typos or tweaks to documentation,
+which do not require a heavy investment of time and attention.
 
 Contributors are also encouraged to contribute new code to enhance ArviZ's
 functionality, also via pull requests.
@@ -13,10 +12,21 @@ to ensure that any new contribution does not strongly overlap with existing
 functionality and open a "Feature Request" issue before starting to work
 on the new feature.
 
-(steps_before_working)=
+:::{note}
+Since version 1.0, ArviZ is organized as a metapackage that brings together functionality
+from three packages: [`arviz-base`](https://github.com/arviz-devs/arviz-base),
+[`arviz-stats`](https://github.com/arviz-devs/arviz-stats), and
+[`arviz-plots`](https://github.com/arviz-devs/arviz-plots).
+
+As a result, contributing to ArviZ typically means contributing to one of these packages rather
+than to the main ArviZ repository itself.
+When browsing issues or pull requests, keep in mind that most activity happens in the
+corresponding package repositories.
+:::
 
+(steps_before_working)=
 ## Steps before starting work
-Before starting work on a pull request double-check that no one else
+Before starting work on a pull request, double-check that no one else
 is working on the ticket in both issue tickets and pull requests.
 
 ArviZ is a community-driven project and always has multiple people working
@@ -25,50 +35,67 @@ that we all make the most of our time and we don't have two contributors
 working on the same changes. Let's see what to do when you encounter the following scenarios:
 
 ### If an issue ticket exists
-If an issue exists check the ticket to ensure no one else has started working on it. If you are first to start work, comment on the ticket to make it evident to others. If the comment looks old or abandoned leave a comment asking if you may start work.
+If an issue exists, check the ticket to ensure no one else has started working on it.
+If you are first to start work, comment on the ticket to make it evident to others.
+If the comment looks old or abandoned, leave a comment asking if you may start work.
 
 ### If an issue ticket doesn't exist
-Open an issue ticket for the issue and state that you'll be solving the issue with a pull request. Optionally create a pull request and add `[WIP]` in the title to indicate Work in Progress.
+Open an issue ticket for the issue and state that you'll be solving the issue with a pull request.
+Optionally create a pull request and add `[WIP]` in the title to indicate Work in Progress.
 
 ### In the event of a conflict
-In the event of two or more people working on the same issue, the general precedence will go to the person who first commented on the issue. If no comments it will go to the first person to submit a PR for review. Each situation will differ though, and the core contributors will make the best judgment call if needed.
+In the event of two or more people working on the same issue,
+the general precedence will go to the person who first commented on the issue.
+If there are no comments, it will go to the first person to submit a PR for review.
+Each situation will differ though, and the core contributors will make the best judgment call if needed.
 
 ### If the issue ticket has someone assigned to it
-If the issue is assigned then precedence goes to the assignee. However, if there has been no activity for 2 weeks from the assignment date, the ticket is open for all again and can be unassigned.
+If the issue is assigned, then precedence goes to the assignee.
+However, if there has been no activity for 2 weeks from the assignment date,
+the ticket is open for all again and can be unassigned.
 
 (dev_summary)=
-## Development process - summary
+## Development process
 
-## Code Formatting
-For code generally follow the
-[TensorFlow's style guide](https://www.tensorflow.org/community/contribute/code_style)
-or the [Google style guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
-Both more or less follow PEP 8.
+TODO: Details and sections to be added...
 
-Final formatting is done with [black](https://github.com/ambv/black).
 
 (docstring_formatting)=
-# Docstring formatting and type hints
+## Docstring formatting
 
-Docstrings should follow the
-[numpy docstring guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+Docstrings should follow the [numpy docstring guide](https://numpydoc.readthedocs.io/).
 Extra guidance can also be found in
 [pandas docstring guide](https://pandas.pydata.org/pandas-docs/stable/development/contributing_docstring.html).
-Please reasonably document any additions or changes to the codebase,
-when in doubt, add a docstring.
+Please reasonably document any additions or changes to the codebase; when in doubt, add a docstring.
+
+While ArviZ does not include type hints in function and method definitions,
+it uses [Docstub](https://docstub.readthedocs.io) to generate `.pyi` files
+from numpydoc-style docstrings.
+For this reason, clear and complete docstrings are important,
+as they are used to generate type information for third-party tools such as type checkers and IDEs.
 
-The different formatting and aim between numpydoc style type description and
-[type hints](https://docs.python.org/3/library/typing.html)
-should be noted. numpydoc style targets docstrings and aims to be human
-readable whereas type hints target function definitions and `.pyi` files and
-aim to help third party tools such as type checkers or IDEs. ArviZ does not
-require functions to include type hints
-however contributions including them are welcome.
 
 ## Documentation for user facing methods
-If changes are made to a method documented in the {ref}`ArviZ API Guide <api>`
-please consider adding inline documentation examples.
-You can refer to {func}`az.plot_posterior <arviz.plot_posterior>` for a good example.
 
-### Tests
-Section in construction
+If changes are made to a method documented in {ref}`ArviZ-base API <arviz_base:api_reference>`,
+{ref}`ArviZ-stats API <arviz_stats:api_reference>`, or {ref}`ArviZ-plots API <arviz_plots:api_reference>`;
+please consider adding inline examples, See Also links,
+References when relevant (e.g., if it implements a published method),
+and Notes with implementation details that might be relevant to users.
+You can refer to {func}`~arviz_plots.plot_dist` and {func}`~arviz_plots.plot_forest` for  good examples.
+
+## Tests
+
+:::{caution} Section in construction
+:::
+
+Tests are run through dedicated tox tasks, however, due to differences in architecture,
+combinations of optional dependencies we might want to test and scope differences between libraries,
+each library defines their own testing tasks.
+
+Moreover, we also have package specific test organization and some extra pytest customization available in some cases.
+Consequently, each library has its own contributing page on how to run the test suite or contribute to it:
+
+* ArviZ-base: coming soon
+* {ref}`ArviZ-stats <arviz_stats:contributing_testing>`
+* {ref}`ArviZ-plots <arviz_plots:contributing_testing>`

docs/source/contributing/contributing_prs.md

@@ -33,7 +33,7 @@ which can nor should follow the Diátaxis framework.
 ArviZ is a library with a strong visualization component.
 This translates for example into some duplicity when it comes to reference content.
 
-Both the {ref}`example_gallery` and the {ref}`api` pages are reference content.
+Both the {ref}`arviz_plots:example_gallery` and the {ref}`arviz_plots:api_reference` pages are reference content.
 The API reference indexes by name and contains the description of each object,
 whereas the Example Gallery indexes by image and to avoid excessive duplication,
 links to the respective API page.

docs/source/contributing/developing_in_docker.md

@@ -1,10 +1,13 @@
 (doc_toolchain)=
 # Documentation toolchain
 
+:::{caution} Some content in this page may be outdated.
+:::
+
 ArviZ documentation is built using a Python documentation tool, [Sphinx](https://www.sphinx-doc.org/en/master/).
 Sphinx converts `rst`(restructured text) files into HTML websites.
 There are different extensions available for converting other types of files
-like markdown, jupyter notebooks, etc. into HTML websites.
+like markdown, Jupyter notebooks, etc. into HTML websites.
 
 ArviZ [docs](https://github.com/arviz-devs/arviz/tree/main/doc/source) consist of `.rst`, `.md` and `.ipynb` files.
 It uses `myst-parser` and `myst-nb` for `.md` and `.ipynb` files.

docs/source/contributing/diataxis_for_arviz.md

@@ -2,8 +2,9 @@
 # Docstring style
 
 Docstrings should follow the
-[numpy docstring guide](https://numpydoc.readthedocs.io/en/latest/format.html). Read more about it {ref}`docstring_formatting`.
-In ArviZ docs, docstrings consit of five main sections, i.e.,
+[numpy docstring guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+
+In ArviZ docs, docstrings consist of five main sections, i.e.,
 1. Short summary
 2. Parameters
 3. Returns
@@ -17,19 +18,25 @@ Docstrings follow the same guide for adding references as the other docs.
 For adding references to external libraries functions and objects, see {ref}`reference_external_libs`. For referencing ArviZ objects, follow {ref}`reference_arviz_objects`.
 
 ## See Also
-In ArviZ docs, we have a lot of interconnected functions both within the library and with external libraries and it can take a lot of time to search for the related functions. It is crucial to add the See Also section to save users time.
-For adding the _See Also_ docstring section, you just need to add the function name. Sphinx will
-automatically add links to other ArviZ objects and functions listed in the _See Also_
+In ArviZ docs, we have a lot of interconnected functions both within the library and with external
+libraries and it can take a lot of time to search for the related functions.
+It is crucial to add the See Also section to save users time.
+For adding the _See Also_ docstring section, you just need to add the function name.
+Sphinx will automatically add links to other ArviZ objects and functions listed in the _See Also_
 section.
 
-For example, let's add {func}`~arviz.hdi` and {func}`~arviz.plot_ppc` in the _See Also_ section.
+For example, let's add {func}`~arviz_stats.hdi` and {func}`~arviz_plots.plot_ppc_dist` in the _See Also_ section.
 
 ```
     See Also
     --------
-    hdi : Calculate highest density interval (HDI) of array for given probability.
-    plot_ppc : plot for posterior/prior predictive checks.
+    arviz_stats.hdi : Calculate highest density interval (HDI) of array for given probability.
+    arviz_plots.plot_ppc_dist : plot for posterior/prior predictive checks.
 ```
 
 ## Kwargs parameters
-All the kwargs parameters in {ref}`plots <plot_api>` modules are passed to the matplotlib or bokeh functions. While writing their description, the functions to which they are being passed must be mentioned. In order to check or add those functions, the process is the same for all the kwargs arguments. Let's read the step-by-step guide for `backend_kwargs` as an example, [here](https://github.com/arviz-devs/arviz/wiki/ArviZ-Hacktoberfest-2021).
+
+All the kwargs parameters in the {doc}`arviz_plots:api/index` modules are passed to the
+Matplotlib or Bbokeh functions. While writing their description, the functions to which they are
+being passed must be mentioned. In order to check or add those functions, the process is the same
+for all the kwargs arguments.

docs/source/contributing/doc_toolchain.md

@@ -160,11 +160,9 @@ how_to_add_to_example_gallery
 :caption: Reference
 
 pr_checklist
-architecture
 content_structure
 docstrings
 syntax_guide
-developing_in_docker
 :::
 
 :::{toctree}
@@ -173,5 +171,4 @@ developing_in_docker
 
 doc_toolchain
 diataxis_for_arviz
-plotting_backends
 :::

docs/source/contributing/docstrings.md

@@ -2,9 +2,15 @@
 # Issue reports
 
 We appreciate being notified of problems with the existing ArviZ code.
-We prefer that issues be filed on the
-[Github Issue Tracker](https://github.com/arviz-devs/arviz/issues),
-rather than on social media or by direct email to the developers.
+We prefer that issues be shared on a Github Issue Tracker rather than on social media or by direct email to the developers.
+If you are unsure if your issue corresponds to a specific package of the ArviZverse,
+you can open an issue in the [main ArviZ repository issue tracker](https://github.com/arviz-devs/arviz/issues).
+On the other hand, if you are certain the issue corresponds to a specific pacakge, use the relevant issue tracker: of the corresponding package repository:
+
+* [ArviZ-base](https://github.com/arviz-devs/arviz-base/issues)
+* [ArviZ-stats](https://github.com/arviz-devs/arviz-stats/issues)
+* [ArviZ-plots](https://github.com/arviz-devs/arviz-stats/issues)
+
 
 Please verify that your issue is not being currently addressed by other
 issues or pull requests by using the GitHub search tool to look for keywords