Backports for v0.10.1 (#2145)

* Docs: Rework `installation` section. (#2130)

* Fix DatasetCollection (#2135)

* Fix `PandasDataset` for Python 3.9 (#2141)

* Docs: Fix running tutorials for publishing docs. (#2138)

* Docs: Fix running tutorials for publishing docs.

* Update requirements.

* Docs: Make notebook templates. (#2122)

* Use of check_github_event.

* Fix issues with hyperparameter tuning tutorial (#2143)

* Apply black to notebooks. (#2144)

Co-authored-by: Jasper <[email protected]>
Co-authored-by: rsnirwan <[email protected]>

.github/workflows/docs.yml

@@ -6,9 +6,6 @@ defaults:
   run:
     shell: bash
 
-env:
-  SKIP_BUILD_NOTEBOOK: ${{!( github.event_name == 'push' || contains(github.event.pull_request.labels.*.name, 'pr:docs-build-notebook'))}}
-
 jobs:
   docs-build:
     runs-on: ubuntu-latest

Justfile

@@ -15,30 +15,18 @@
 # specific language governing permissions and limitations
 # under the License.
 
-ROOTDIR := invocation_directory()
+ROOTDIR := justfile_directory()
 MD2IPYNB := ROOTDIR + "/docs/md2ipynb.py"
 
-skip_build_notebook := env_var_or_default("SKIP_BUILD_NOTEBOOK", "false")
-
-
-docs: release
+docs: compile_notebooks
   make -C docs html # SPHINXOPTS=-W
 
 clean:
   git clean -ff -d -x --exclude="{{ROOTDIR}}/tests/externaldata/*" --exclude="{{ROOTDIR}}/tests/data/*" --exclude="{{ROOTDIR}}/conda/"
 
-compile_notebooks:
-  if [ {{skip_build_notebook}} = "true" ] ; \
-  then \
-    find docs/tutorials/**/*.md.input | sed 'p;s/\.input//' | xargs -n2 cp; \
-  else \
-    python -m ipykernel install --user --name docsbuild; \
-    python {{MD2IPYNB}} --kernel docsbuild "docs/tutorials/**/*.md.input"; \
-  fi;
-
-dist_notebooks: compile_notebooks
-  cd docs/tutorials && \
-  find * -type d -prune | grep -v 'tests\|__pycache__' | xargs -t -n 1 -I{} zip --no-dir-entries -r {}.zip {} -x "*.md" -x "__pycache__" -x "*.pyc" -x "*.txt" -x "*.log" -x "*.params" -x "*.npz" -x "*.json"
+compile_notebooks mode="release":
+    python -m ipykernel install --user --name docsbuild
+    python {{MD2IPYNB}} --kernel docsbuild docs/tutorials/**/*.md.template --mode {{mode}}
 
-release: dist_notebooks
+release:
   python setup.py sdist

docs/getting_started/install.md

@@ -0,0 +1,159 @@
+
+# Installation
+
+GluonTS is available from PyPi via:
+
+```sh
+pip install gluonts
+````
+
+```{attention}
+**GluonTS uses a minimal dependency model.**
+
+This means that to use most models and features additional dependencies need to
+be installed. See the next section for more information.
+
+```
+
+## Optional and Extra Dependencies
+
+Python has the notion of [extras](https://peps.python.org/pep-0508/#extras)
+-- dependencies that can be optionally installed to unlock certain features of
+a pacakge.
+
+When installing a package, they are passed via ``[...]`` after the package
+name:
+
+```sh
+pip install some-package[extra-1,extra-2]
+````
+
+We make extensive use of optional dependencies in GluonTS to keep the amount of
+required dependencies minimal. To still allow users to opt-in to certain
+features, we expose many extra dependencies.
+
+For example, we offer support for reading and writing Arrow and Parquet based
+datasets using [Apache Arrow](https://arrow.apache.org/). However, it is a
+hefty dependency to require, especially if one has no need for it. Thus, we
+offer the ``arrow``-extra, which installs the required packages and can be
+simply enabled using:
+
+```sh
+pip install gluonts[arrow]
+````
+
+### Models
+
+
+#### PyTorch
+
+Models written using [PyTorch](https://pytorch.org/) are available via the
+``gluonts.torch`` subpackage.
+
+In addition to PyTorch we require [PyTorch Lightning](https://www.pytorchlightning.ai/)
+to be installed as well.
+
+Both required dependencies are included in the ``torch``-extra:
+
+```sh
+pip install gluonts[torch]
+````
+
+
+#### MXNet
+
+MXNet based models require a version of ``mxnet`` to be installed.
+
+```{note}
+
+MXNet provives different package for CPU and GPU usages. Please refer to its
+[documentation](https://mxnet.apache.org/versions/1.9.1/get_started?) to
+select the right version fitting your use-case.
+
+```
+
+The ``mxnet``-extra will install a CPU-only version:
+
+```sh
+pip install gluonts[mxnet]
+
+````
+
+
+#### 3rd Party
+
+##### R-Forecast
+
+GluonTS includes a thin wrapper for calling the ``R`` `forecast` package.
+
+In order to use it you need to install [``R``](https://www.r-project.org/) and
+install the `forecast` package:
+
+```sh
+R -e 'install.packages(c("forecast", "nnfor"), repos="https://cloud.r-project.org")'
+```
+
+In addition, we require rpy2 to be installed:
+
+```sh
+pip install 'rpy2>=2.9.*,<3.*'
+````
+
+##### Prophet
+
+The [Prophet](https://facebook.github.io/prophet/) forecasting library is
+available via `gluonts.model.prophet` and requires the ``prophet`` package to
+be installed.
+
+The ``prophet``-extra also depends on it:
+
+```sh
+pip install gluonts[prophet]
+```
+
+
+### Datasets
+
+#### JSON
+
+Since Python's build in ``json`` package is known to be relatively slow, we use
+faster implementations if available: ``orjson`` (recommended) and ``ujson``.
+
+You can install ``orjson`` via:
+
+```sh
+pip install orjson
+```
+
+```{hint}
+GluonTS will emit a warning if neither ``orjson`` nor ``ujson`` are installed.
+There is no functional difference between the different implementations, but
+especially when working with larger datasets, performance can be notably
+impacted when relying on the default ``json`` package.
+```
+
+#### Arrow
+
+GluonTS support [Parquet](https://en.wikipedia.org/wiki/Apache_Parquet) files
+using [``PyArrow``](https://arrow.apache.org/docs/python/index.html).
+
+Further, [arrow's custom data formats](https://arrow.apache.org/docs/python/ipc.html)
+are also supported.
+
+To utilise these, either install the ``pyarrow`` package or use the
+``arrow``-extra:
+
+```sh
+pip install gluonts[arrow]
+```
+
+### Other
+
+#### Shell
+
+The ``shell`` module offers integration with Amazon SageMaker and is available
+through:
+
+```sh
+pip install gluonts[shell]
+```