Docs/add howto

[phackstock]

Closes #142.
Opened in favor of #143.

This is my first attempt at a "how to" detailing the common pitfall of adding a model mapping without the corresponding region definition files.
As the "how to" referenced the nomenclature validate-project cli command, I added some additional docstring explanation that does not seem to be rendered currently by sphinx-click. Additionally, the direct referencing of a cli command seems to not be possible at the moment (https://sphinx-click.readthedocs.io/en/latest/usage/#cross-referencing) so I liked the CLI page.

A preview of the updated docs is rendered here: https://nomenclature-iamc.readthedocs.io/en/docs-add-howto/

[danielhuppmann]

Thanks for the first draft @phackstock. I made some suggestions, please also revise for more concise language.

Most importantly, I would frame this page as "Model registration", because we may want to add other types of model registration (e.g., use MAGICC for post-processing) here.

[phackstock]

Thanks for the first round of comments @danielhuppmann. I implemented them and made the language more concise. Hope that's a step in the right direction.
@luciecastella, please feel free to have a read at https://nomenclature-iamc.readthedocs.io/en/docs-add-howto/user_guide/howto.html and let me know if the explanation makes sense to you.

[luciecastella]

The explanation makes sense yes! I find the difference between native and common regions hard to grasp in general and in this article, but that might just be because I do not work with the data. I'll let you see if it is useful to add something on that or if people working with the package are expected to know it.

[phackstock]

@luciecastella thanks for the quick review. Good to hear that it made sense to you.
The difference between native regions and common regions is that the former are reported directly by the model itself and the latter are calculated, by us in this case, by summing up any number of model native regions. Common regions exist so that different models with different native spatial resolution can be compared.
Let's say we have two models a and b and we want to compare them. model_a natively reports a region called "Europe" while model_b reports "Western Europe" and "Eastern Europe". In this case we might want to define "Europe" as a common region and for model_b create it from summing up Western and Eastern Europe.
Hope that made sense.
Usually the modelers are familiar with the concept of native and common regions so I think in a quick how-to guide it should be fine to not explain it. In the more in-depth model mapping part of the documentation it is explained anyway. But maybe adding another reference might be a good idea.

[danielhuppmann]

Two more minor suggestions inline, then good to be merged.

[danielhuppmann]

Thanks @luciecastella for your comments. Please also use the "Approve" feature so that your approval can easily be seen in the status overview of the PR.

Based on your remarks, I started a new issue #145, which you and @phackstock can tackle in a follow-up PR.

[luciecastella]

All good to me :)

[phackstock]

I renamed the file from howto.rst to model-registration.rst and tried to make the sentence about the native region file more easily understandable. If that looks good to you @danielhuppmann, I'd go ahead with the merge then.
Also once we have a new release I think it would be a good idea to link this model registration section on the README for the workflows of each active project. I'd also add it to the workflow template repo.

[danielhuppmann]

I think it would be a good idea to link this model registration section on the README for the workflows of each active project. I'd also add it to the workflow template repo.

Yes, good idea.