Contributor guidelines could be more detailed

[khaeru]

The contributor guidelines in the documentation include this short section on “Coding style”, but could be expanded to include:

• Specific steps for adding tutorials, including those accompanying new features or message_ix.tools. These would include:
  • Conforming to the tutorial style guide developed by @behnam2015 @OFR-IIASA and others.
  • Adding a line to test_tutorials.py so that the parametrized test function runs the tutorial (as noted at #196).
• Development rules of thumb such as these ones currently on the wiki.
• (anything else)

[JamesFrierson1]

Hello! I'm a new technical writer looking to grow my experience by contributing to project documentation. I'd be happy to help with your project if I can!

[JamesFrierson1]

Created #202

[khaeru]

@JamesFrierson1 thanks for the interest. To expand on this:

• Specific steps for adding tutorials, including those accompanying new features or message_ix.tools. These would include:
  • Conforming to the tutorial style guide developed by @behnam2015 @OFR-IIASA and others.
  • Adding a line to test_tutorials.py so that the parametrized test function runs the tutorial (as noted at #196).

…here is a brief/unedited set of notes from our colleagues towards that style guide. It would be great to include these in #202 so that it will close this issue. Please feel free to ask any questions you need for context.

Tutorial style guide notes

Tutorial structure: * baseline * basic_modelling_features (basic) * emission_bounds * emission_taxes * fossil_resources * advanced_modelling_features (adv) * renewables * firm_capacity * flexible_generation * renewable_resources * addon_technologies * share_constraints * tools * e.g. to_excel or read_excel * rscript * ?? Naming scheme of tutorials: * westeros__.ipynb * name all in lower case Style guide tutorial structure: * Tutorial introduction: * general overview of tutorial * expected outcome * explanation of which features are covered * if there are tutorials which are interlinked or part of a series, reference these and provide links. * Description of individual steps: * brief explanation the step * link to relevant mathematical documentation * Results: * Results should be retrieved using the generic reporting tool * Plots to depict results should use pyam (https://github.com/IAMconsortium/pyam/) Style guide on text formatting: * To be defined... General requirements: * Where relevant, provide links to publication or source, which further details methodology, data or other packages used. * Providing the mathematical formulation in the tutorial itself is optional. * Making a tutorial such that it can also be viewed, as a presentation is optional. * General formatting: * Framework specific variables and parameters or functions must be in in italic. * E.g.: This next step will show the user how to add investment costs (inv_cost) to a technology. Additional Notes: * All users of the message_ix framework can contribute tutorials, as long as the tutorials adhere to guidelines provided above. * Tutorials will become part of the general message_ix test suite and will become publicly available. Open Questions/Issues * Shall we create a checklist for the pre-requisites similar to those of a general PR? * Update README.rst * Getting tutorials should be removed, as these will come as part of the installation process * Install all packages required to run tutorials: * Requirements to run rscript based tutorials?

[JamesFrierson1]

Hi @khaeru thank you for the additional info! I'll be happy to make a pass at adding this and will comment here if I have any questions

[JamesFrierson1]

Finished incorporating your notes. Please let me know if you see any potential improvements 👍

[khaeru]

Closed via #230.