Add intersphinx mapping

doc/source/conf.py

@@ -37,6 +37,7 @@
     "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx_click",
 ]
 
@@ -95,7 +96,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# prolog for all rst files
+# Intersphinx configuration
+intersphinx_mapping = {
+    "pyam": ("https://pyam-iamc.readthedocs.io/en/stable/", None),
+}
+
+# Prolog for all rst files
 rst_prolog = """
 
 .. |br| raw:: html

doc/source/getting_started.rst

@@ -1,5 +1,7 @@
 .. _getting-started:
 
+.. currentmodule:: nomenclature
+
 Getting started
 ===============
 
@@ -10,13 +12,13 @@ processing, which consists of renaming of model “native regions” and aggrega
 “common regions” used in a project.
 
 There are two main classes that the user interacts with when using the nomenclature
-package, **DataStructureDefinition** and **RegionProcessor** (a full list of all classes can be found in :ref:`api`). 
+package, :class:`DataStructureDefinition` and :class:`RegionProcessor`.
 
-A **DataStructureDefinition** contains codelists which define allowed *variables*
+A :class:`DataStructureDefinition` contains codelists which define allowed *variables*
 (including units) and *regions* to be used in a model comparison or scenario exercise
 following the IAMC data format.
 
-A **RegionProcessor**  is used to facilitate region processing for model comparison
+A :class:`RegionProcessor` is used to facilitate region processing for model comparison
 studies. It holds a list of model specific mappings which define renaming of native
 regions and aggregation to common regions.
 
@@ -101,14 +103,14 @@ The following outlines how to use the nomenclature package:
 
 **Notes**
 
-* The pyam library is required as *process* takes a *pyam.IamDataFrame* as input.
+* The function :func:`process` takes a :class:`pyam.IamDataFrame` as input.
 
-* *DataStructureDefinition* and *RegionProcessor* are initialized from directories
-  containing yaml files. See :ref:`dir-structure` for details. 
+* :class:`DataStructureDefinition` and :class:`RegionProcessor` are initialized from
+  directories containing yaml files. See :ref:`dir-structure` for details.
 
-* The processor argument of *process* is optional and may only to be used if there are  
-  model mappings. See :ref:`toplevel-functions` for details.
+* The processor argument of func:`process` is optional and may only to be used if there
+  are model mappings. See :ref:`toplevel-functions` for details.
 
-* If not all dimensions of the **DataStructureDefinition** should be validated, a
+* If not all dimensions of the :class:`DataStructureDefinition` should be validated, a
   *dimensions* argument in form of a list of strings can be provided. Only the provided
   dimensions will then be validated. See :ref:`toplevel-functions` for details.

nomenclature/core.py

@@ -28,20 +28,20 @@ def process(
 
     Parameters
     ----------
-    df : pyam.IamDataFrame
-        Input data to be validated and aggregated.
-    dsd : DataStructureDefinition
+    df : :class:`pyam.IamDataFrame`
+        Scenario data to be validated and aggregated.
+    dsd : :class:`DataStructureDefinition`
         Codelists that are used for validation.
     dimensions : list, optional
         Dimensions to be used in the validation, defaults to all dimensions defined in
-        *dsd*
-    processor : RegionProcessor, optional
-        Region processor that will perform region renaming and aggregation if provided
+        `dsd`
+    processor : :class:`RegionProcessor`, optional
+        Region processor to perform region renaming and aggregation (if given)
 
     Returns
     -------
-    pyam.IamDataFrame
-        Processed data frame
+    :class:`pyam.IamDataFrame`
+        Processed scenario data
     """
     # The deep copy is needed so we don't alter dsd in dimensions.remove("region")
     dimensions = copy.deepcopy(dimensions or dsd.dimensions)

nomenclature/definition.py

@@ -45,9 +45,8 @@ def validate(self, df: IamDataFrame, dimensions: list = None) -> None:
 
         Parameters
         ----------
-        df : IamDataFrame
-            An IamDataFrame to be validated against the codelists of this
-            DataStructureDefinition.
+        df : :class:`pyam.IamDataFrame`
+            Scenario data to be validated against the codelists of this instance.
         dimensions : list of str, optional
             Dimensions to perform validation (defaults to all dimensions of self)
 

setup.cfg

@@ -32,9 +32,9 @@ docs =
     sphinx-click
     numpydoc
 
-[flake8]
-max-line-length = 88
-
 [options.entry_points]
 console_scripts =
     nomenclature = nomenclature:cli
+
+[flake8]
+max-line-length = 88