Add pysquirrel to docs (#395)

* Add pysquirrel to docs

* Add nuts to api table of contents

docs/api.rst

@@ -14,4 +14,5 @@ API documentation
    api/codelist
    api/regionprocessor
    api/countries
+   api/nuts
    api/testing

docs/api/nuts.rst

@@ -0,0 +1,30 @@
+.. _nuts:
+
+.. currentmodule:: nomenclature.nuts
+
+NUTS classification
+===================
+
+The :class:`nomenclature` package makes use of the :class:`pysquirrel` package
+(`link <https://github.com/iiasa/pysquirrel>`_) to provide a utility for region
+names based on the `NUTS classification <https://ec.europa.eu/eurostat/web/nuts>`_. 
+
+This feature allows users to define an agreed list of territorial units with 
+multiple levels of resolution, adding functionality to facilitate scenario 
+analysis and model comparison.
+
+The full list of NUTS regions is accessible in Eurostat's `Excel file`_.
+
+.. _GitHub: https://github.com/IAMconsortium/nomenclature/blob/main/nomenclature/countries.py
+
+.. _`Excel template`: https://ec.europa.eu/eurostat/documents/345175/629341/NUTS2021-NUTS2024.xlsx
+
+.. code:: python
+
+  from nomenclature import nuts
+
+  # list of NUTS region codes
+  nuts.codes
+  
+  # list of NUTS region names
+  nuts.names

docs/user_guide/config.rst

@@ -78,6 +78,27 @@ the nomenclature package will add all countries to the *region* codelist.
 
 More details on the list of countries can be found here: :ref:`countries`.
 
+Adding NUTS to the region codelist
+----------------------------------
+
+By setting *definitions.region.nuts* (optional) in the configuration file:
+
+.. code:: yaml
+
+  definitions:
+    region:
+      nuts:
+        nuts-1: [ AT, BE, CZ ]
+        nuts-2: [ AT ]
+        nuts-3: [ AT, BE ]
+
+the nomenclature package will add the selected NUTS regions to the *region* codelist.
+
+In the example above, the package will add all NUTS (1, 2, and 3) for Austria,
+NUTS 1 and 3 for Belgium, and NUTS 1 for Czechia.
+
+More details on the list of NUTS regions can be found here: :ref:`nuts`.
+
 Specify dimensions to be read
 -----------------------------