contributing docs and workflow improvements (#144)

Author: OriolAbril

docs/source/contributing/updating_example_data.md

@@ -0,0 +1,16 @@
+# Updating the example data
+
+Metadata for ArviZ's example datasets (which are loadable by {func}`~arviz_base.load_arviz_data`) is stored in the [`arviz_example_data`](https://github.com/arviz-devs/arviz_example_data) repository.
+This repo has been embedded into the `arviz` repo at `/src/arviz_base/example_data` using [git subtree](https://www.atlassian.com/git/tutorials/git-subtree) with the following command:
+
+```bash
+$ git subtree add --prefix src/arviz_base/example_data https://github.com/arviz-devs/arviz_example_data.git main --squash
+```
+
+When `arviz_example_data` is updated, the subtree within the `arviz` repo also needs to be updated with the following command:
+
+```bash
+$ git subtree pull --prefix src/arviz_base/example_data https://github.com/arviz-devs/arviz_example_data.git main --squash
+```
+
+Moreover, to keep the size of the wheel and sdist for `arviz-base` as small as possible, the `code` folder of `arviz_example_data` is also removed as it contains some jupyter notebooks and csv files.

docs/source/index.md

@@ -78,6 +78,13 @@ ArviZ in Context <https://arviz-devs.github.io/EABM/>
 api/index
 :::
 
+:::{toctree}
+:caption: Contributing
+:hidden:
+
+contributing/updating_example_data
+:::
+
 :::{toctree}
 :caption: About
 :hidden:

tox.ini

@@ -7,6 +7,8 @@ envlist =
 # See https://tox.readthedocs.io/en/latest/example/package.html#flit
 isolated_build = True
 isolated_build_env = build
+labels =
+    dev = check, cleandocs, docs, livedocs, viewdocs, py311, py312, py313, nightlies
 
 [gh-actions]
 python =
@@ -15,6 +17,7 @@ python =
     3.13: py313-coverage
 
 [testenv]
+description = Run ArviZ-base tests
 basepython =
     py311: python3.11
     py312: python3.12
@@ -35,13 +38,14 @@ commands =
     pytest {env:PYTEST_MARKERS:} {env:PYTEST_EXTRA_ARGS:} {posargs:-vv}
 
 [testenv:nightlies]
+description = Run test job with nightly pre-releases of scientific python packages
 install_command = python -I -m pip install --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple {opts} {packages}
 pip_pre = true
 setenv =
   NIGHTLIES=TRUE
 
 [testenv:check]
-description = perform style checks
+description = Perform style checks
 extras =
     check
 allowlist_externals =
@@ -52,7 +56,7 @@ commands =
     python -m build
 
 [testenv:docs]
-description = build HTML docs
+description = Build HTML docs
 setenv =
     READTHEDOCS_PROJECT = arviz_base
     READTHEDOCS_VERSION = latest
@@ -61,15 +65,24 @@ extras =
 commands =
     sphinx-build -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -v -bhtml
 
+[testenv:livedocs]
+description = Build live preview of HTML docs with automatic updates
+base = docs
+extras =
+    doc
+    sphinx-autobuild
+commands =
+    sphinx-autobuild -d "{toxworkdir}/docs_doctree" docs/source "{toxworkdir}/docs_out" --color -v -bhtml
+
 [testenv:cleandocs]
-description = clean HTML outputs docs
+description = Clean HTML doc build outputs
 skip_install = true
 allowlist_externals = rm
 commands =
     rm -r "{toxworkdir}/docs_out" "{toxworkdir}/docs_doctree" "{toxworkdir}/jupyter_execute" docs/source/api/generated docs/source/contributing/generated
 
 [testenv:viewdocs]
-description = open HTML docs
+description = View HTML docs with the default browser
 skip_install = true
 commands =
     python -m webbrowser "{toxworkdir}/docs_out/index.html"