From db0a4e3e2f78f93a7961ba0fd5a6472cf2d53685 Mon Sep 17 00:00:00 2001 From: Daniel Huppmann Date: Fri, 10 Jun 2022 09:54:52 +0200 Subject: [PATCH 1/4] Migrate variable-naming-conventions to own docs page --- doc/source/user_guide/codelist.rst | 20 ++---------------- doc/source/user_guide/variable-guidelines.rst | 21 +++++++++++++++++++ 2 files changed, 23 insertions(+), 18 deletions(-) create mode 100644 doc/source/user_guide/variable-guidelines.rst diff --git a/doc/source/user_guide/codelist.rst b/doc/source/user_guide/codelist.rst index 2b70cd82..2400c1ea 100644 --- a/doc/source/user_guide/codelist.rst +++ b/doc/source/user_guide/codelist.rst @@ -67,25 +67,9 @@ examples for all three options: While not strictly necessary a *description* attribute with a short description of the variable is encouraged. -The yaml format allows *any* number of additional arbitrary named attributes. +The yaml format allows *any* number of additional arbitrary named attributes. -Guidelines and variable naming conventions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The variable name should adhere to the following conventions: - -* A *|* (pipe) character indicates levels of hierarchy. -* Do not use spaces before and after the *|* character, but add a - space between words (e.g., *Primary Energy|Non-Biomass Renewables*). -* Do not use abbreviations (e.g, *PHEV*) unless strictly necessary. -* Do not use abbreviations of statistical operations (*min*, *max*, - *avg*) but always spell out the word. -* All words must be capitalised (except for *and*, *w/*, *w/o*, etc.). -* Add hierarchy levels where it might be useful in the future, e.g., - use *Electric Vehicle|Plugin-Hybrid* instead of *Plugin-Hybrid - Electric Vehicle*. -* Do not include words like *Level* or *Quantity* in the variable, - because this should be clear from the context or unit. +Please also take a look at the :ref:`variable-guidelines` when proposing new items. .. _region_aggregation_attributes: diff --git a/doc/source/user_guide/variable-guidelines.rst b/doc/source/user_guide/variable-guidelines.rst new file mode 100644 index 00000000..6801da08 --- /dev/null +++ b/doc/source/user_guide/variable-guidelines.rst @@ -0,0 +1,21 @@ +.. _variable-guidelines: + +Variable naming conventions +=========================== + +A variable name should adhere to the following conventions: + +* A *|* (pipe) character indicates levels of hierarchy. +* Do not use spaces before and after the *|* character, but add a + space between words (e.g., *Primary Energy|Non-Biomass Renewables*). +* Do not use abbreviations (e.g, *PHEV*) unless strictly necessary. +* Do not use abbreviations of statistical operations (*min*, *max*, + *avg*) but always spell out the word. +* All words must be capitalised (except for *and*, *w/*, *w/o*, etc.). +* Add hierarchy levels where it might be useful in the future, e.g., + use *Electric Vehicle|Plugin-Hybrid* instead of *Plugin-Hybrid + Electric Vehicle*. +* Do not include words like *Level* or *Quantity* in the variable, + because this should be clear from the context or unit. + +Read more about the required/expected attributes of a :ref:`variable`. \ No newline at end of file From 3f3af22cd946f1793292c529d4cd84dfbad324d4 Mon Sep 17 00:00:00 2001 From: Daniel Huppmann Date: Fri, 10 Jun 2022 09:55:02 +0200 Subject: [PATCH 2/4] Add to TOC --- doc/source/user_guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/user_guide.rst b/doc/source/user_guide.rst index 48e8d150..05dbcfec 100644 --- a/doc/source/user_guide.rst +++ b/doc/source/user_guide.rst @@ -45,5 +45,6 @@ the RegionProcessor and validated using DataStructureDefinition. user_guide/directory-structure user_guide/codelist + user_guide/variable-guidelines user_guide/model-mapping user_guide/local-usage From 0d0b032b8639b1367664473e7f108cd66bfad4f1 Mon Sep 17 00:00:00 2001 From: Daniel Huppmann Date: Fri, 10 Jun 2022 09:59:28 +0200 Subject: [PATCH 3/4] Add reference to Python-dict docs --- doc/source/conf.py | 1 + doc/source/user_guide/codelist.rst | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index f2d24e09..c0f6e353 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -99,6 +99,7 @@ # Intersphinx configuration intersphinx_mapping = { + "python": ("https://docs.python.org/", None), "pyam": ("https://pyam-iamc.readthedocs.io/en/stable/", None), } diff --git a/doc/source/user_guide/codelist.rst b/doc/source/user_guide/codelist.rst index 2400c1ea..c2abfbb9 100644 --- a/doc/source/user_guide/codelist.rst +++ b/doc/source/user_guide/codelist.rst @@ -31,9 +31,9 @@ than simple strings, detailed in the following. Variable ^^^^^^^^ -An entry in a variable code list, *must be* a mapping (translated to python as a -dictionary). It maps the **name** of an allowed variable to, at least, one key-value -pair defining the allowed **unit(s)** for the variable. +An entry in a variable codelist *must be* a mapping (or a :class:`dict` in Python). +It maps the **name** of an allowed variable to, at least, one key-value pair defining +the allowed **unit(s)** for the variable. This is an example for a valid entry in a variable codelist: From a4879d6ce120b2c355c72cf99356a99009debd96 Mon Sep 17 00:00:00 2001 From: Daniel Huppmann Date: Fri, 10 Jun 2022 09:59:38 +0200 Subject: [PATCH 4/4] Minor edits --- doc/source/user_guide/codelist.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/source/user_guide/codelist.rst b/doc/source/user_guide/codelist.rst index c2abfbb9..0407d7d5 100644 --- a/doc/source/user_guide/codelist.rst +++ b/doc/source/user_guide/codelist.rst @@ -40,8 +40,8 @@ This is an example for a valid entry in a variable codelist: .. code:: yaml - Allowed variable name: + description: A short explanation or definition unit: A unit - description: A short description : Some text, value, boolean or list (optional) The **unit** attribute is **required** and its value should be compatible with the @@ -53,7 +53,7 @@ The unit attribute can be: * a list of strings -> a number of allowed units for the variable * empty -> a *dimensionless* variable -examples for all three options: +Examples for all three options: .. code:: yaml @@ -62,10 +62,9 @@ examples for all three options: - Multi unit variable: unit: [unit 1, unit 2] - Dimensionless variable: - unit: + unit: -While not strictly necessary a *description* attribute with a short description of the -variable is encouraged. +A **description** attribute with an explanation or definition is recommended. The yaml format allows *any* number of additional arbitrary named attributes.