.. _ref-dev-checklist: POD development checklist ========================= This section lists all the steps that need to be taken in order to submit a POD for inclusion in the MDTF framework. Code and documentation submission --------------------------------- The material in this section must be submitted though a `pull request `__ to the `NOAA-GFDL GitHub repo `__. This is described in :doc:`dev_git_intro`. The `example POD `__ should be used as a reference for how each component of the submission should be structured. POD source code ^^^^^^^^^^^^^^^ All scripts should be placed in a subdirectory of ``diagnostics/``. Among the scripts, there should be 1) a main driver script, 2) a template html, and 3) a ``settings.jsonc`` file. The POD directory and html template should be named after your POD's short name. - For instance, ``diagnostics/convective_transition_diag/`` contains its driver script ``convective_transition_diag.py``, ``convective_transition_diag.html``, and ``settings.jsonc``, etc. - The framework will call the driver script, which calls the other scripts in the same POD directory. - If you need a new Conda environment, add a new .yml file to ``src/conda/``, and install the environment using the ``conda_env_setup.sh`` script as described in the :doc:`Getting Started `. POD settings file ^^^^^^^^^^^^^^^^^ The format of this file is described in :doc:`dev_settings_quick` and in more detail in :doc:`ref_settings`. POD html template for output ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The html template will be copied by the framework into the output directory to display the figures generated by the POD. You should be able to create a new html template by simply copying and modifying the example templates from existing PODs even without prior knowledge about html syntax. Preprocessing scripts for digested data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The "digested" supporting data policy is described in :numref:`ref-pod-digested-data`. For maintainability and provenance purposes, we request that you include the code used to generate your POD's "digested" data from raw data sources (any source of data that's permanently hosted). This code will not be called by the framework and will not be used by end users, so the restrictions and guidelines concerning the POD code don't apply. POD documentation ^^^^^^^^^^^^^^^^^ - The documentation for the framework is automatically generated using `sphinx `__, which works with files in `reStructured text `__ (reST, ``.rst``) format. In order to include :doc:`documentation for your POD `, we require that it be in this format. + Use the `example POD documentation `__ as a template for the information required for your POD, by modifying its .rst `source code `__. This should include a one-paragraph synopsis of the POD, developers’ contact information, required programming language and libraries, and model output variables, a brief summary of the presented diagnostics as well as references in which more in-depth discussions can be found. + The .rst files and all linked figures should be placed in a ``doc`` subdirectory under your POD directory (e.g., ``diagnostics/convective_transition_diag/doc/``) and put the .rst file and figures inside. + The most convenient way to write and debug reST documentation is with an online editor. We recommend `https://livesphinx.herokuapp.com/ `__ because it recognizes sphinx-specific commands as well. + For reference, see the reStructured text `introduction `__, `quick reference `__ and `in-depth guide `__. + Also see a reST `syntax comparison `__ to other text formats you may be familiar with. - For maintainability, all scripts should be self-documenting by including in-line comments. The main driver script (e.g., ``convective_transition_diag.py``) should contain a comprehensive header providing information that contains the same items as in the POD documentation, except for the "More about this diagnostic" section. - The one-paragraph POD synopsis (in the POD documentation) as well as a link to the full documentation should be placed at the top of the html template (e.g., ``convective_transition_diag.html``). Preprocessing script documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The "digested" supporting data policy is described in :numref:`ref-pod-digested-data`. For maintainability purposes, include all information needed for a third party to reproduce your POD's digested data from its raw sources in the ``doc`` directory. This information is not published on the documentation website and can be in any format. In particular, please document the raw data sources used (DOIs/versioned references preferred) and the dependencies/build instructions (eg. conda environment) for your preprocessing script. Sample and supporting data submission ------------------------------------- Data hosting for the MDTF framework is currently managed manually. The data is currently hosted via anonymous FTP on UCAR's servers. Please contact the MDTF team leads via email to arrange a data transfer. Digested observational or supporting data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The "digested" supporting data policy is described in :numref:`ref-pod-digested-data`. Create a directory under ``inputdata/obs_data/`` named after the short name, and put all your *digested* observation data in (or more generally, any quantities that are independent of the model being analyzed). - Digested data should be in the form of numerical data, not figures. - The data files should be small (preferably a few MB) and just enough for producing figures for model comparison. - If you really cannot reduce the data size or require GB of space, consult with the lead team. Sample model data ^^^^^^^^^^^^^^^^^ For PODs dealing with atmospheric phenomena, we recommend that you use sample data from the following sources, if applicable: - A timeslice run of `NCAR CAM5 `__ - A timeslice run of `GFDL AM4 `__ (contact the leads for password).