Documentation update: new model porting

mjs2369 commented 1 year ago

Description:

In the DART documentation, there are multiple sections that cover the same material on how to use a new model with DART: https://docs.dart.ucar.edu/en/latest/models/README.html#hints-for-porting-a-new-model-to-dart https://docs.dart.ucar.edu/en/latest/guide/advice-for-new-collaborators.html

These two documents have been reorganized so that /DART/guide/advice-for-new-collaborators.html only contains information pertaining to whether a model/project is compatible with DART and /DART/models/README.html#hints-for-porting-a-new-model-to-dart only contains information on the procedure itself for porting new models to DART.

The documentation found at /DART/models/README.html#hints-for-porting-a-new-model-to-dart has been removed from the README in the models directory and placed into its own documentation page, which is currently still located in the models directory at /DART/models/instructions-for-porting-a-new-model-to-dart.rst

The documents have been given new titles to more appropriately describe their content.

Finally, these documents have been generally reviewed and updated to improve clarity, remove outdated instructions, and ensure that all related information/documents are appropriately linked.

Fixes issue

Fixes #439

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
[x] Documentation update

Documentation changes needed?

[x] My change requires a change to the documentation.
- [x] I have updated the documentation accordingly.

Tests

Please describe any tests you ran to verify your changes.

Built the documentation with Read the Docs.

Checklist for merging

[ ] Updated changelog entry
[x] Documentation updated
[ ] Update conf.py

Checklist for release

[ ] Merge into main
[ ] Create release from the main branch with appropriate tag
[ ] Delete feature-branch

Testing Datasets

[ ] Dataset needed for testing available upon request
[ ] Dataset download instructions included
[x] No dataset needed

mjs2369 commented 1 year ago

@hkershaw-brown there are two things that I am still unsure of in terms of file placement and naming.

As described above, I've removed the content from the README in the models directory and instead simply placed that content into its own document that is still located in the models dir. https://docs.dart.ucar.edu/en/docs-new_model_porting/models/instructions-for-porting-a-new-model-to-dart.html#porting-new-models Do you think it would be better to move the new documetnation file to another location, such as the /guide directory?

The second thing is the title of the document at https://docs.dart.ucar.edu/en/docs-new_model_porting/guide/advice-for-new-collaborators.html I changed it from Working with collaborators on porting new models to Creating a DART interface to a new model, but I was thinking that another title might be more fitting. This is because this doc does not detail the process of creating a DART interface to a new mode at all, but rather whether or not a new user might want to use DART with their model. Maybe another title like Can I use a different model with DART?would be better?

Please let me know what you think.

mjs2369 commented 1 year ago

One last note: I think that I still need to add a note to the instructions for porting new models (now /DART/models/instructions-for-porting-a-new-model-to-dart.html#porting-new-models ) that the user will need to recompile with ./quickbuild.sh if they make any changes to the model_mod code.

hkershaw-brown commented 1 year ago

@hkershaw-brown there are two things that I am still unsure of in terms of file placement and naming.

As described above, I've removed the content from the README in the models directory and instead simply placed that content into its own document that is still located in the models dir. https://docs.dart.ucar.edu/en/docs-new_model_porting/models/instructions-for-porting-a-new-model-to-dart.html#porting-new-models Do you think it would be better to move the new documetnation file to another location, such as the /guide directory?

You're right, we do have a mixture of documentation in /guide and documentation near the source code. I think for now, in the models directory is fine. Nice work adding the _Porting new models: so we can move files around without breaking links if/when we do reorganize the documentation.

The second thing is the title of the document at https://docs.dart.ucar.edu/en/docs-new_model_porting/guide/advice-for-new-collaborators.html I changed it from Working with collaborators on porting new models to Creating a DART interface to a new model, but I was thinking that another title might be more fitting. This is because this doc does not detail the process of creating a DART interface to a new mode at all, but rather whether or not a new user might want to use DART with their model. Maybe another title like Can I use a different model with DART?would be better?

Yes I think you are right here, it does need a more appropriate title. It's a bit unclear to me who the intended audience is for this whole RUN DART WITH YOUR MODEL section - going back to your comment above, we do need to tackle the organization of the documentation (big project for some/all the group). For now, maybe Can I run my model with DART? to match RUN DART WITH YOUR MODEL

hkershaw-brown commented 1 year ago

I've changed my mind on where to put the file. I think guide is the place for user guide documentation.

guide/instructions-for-porting-a-new-model-to-dart.rst

And add this to the table of contents (toctree) DART/README.rst

244 .. toctree::
245    :maxdepth: 2
246    :caption: Run DART with your model
247 
248    guide/advice-for-new-collaborators
249    guide/instructions-for-porting-a-new-model-to-dart.rst 
250    DART build system <guide/quickbuild.rst>
251    guide/assimilation-complex-model

mjs2369 commented 1 year ago

@hkershaw-brown sounds good to combine the two in the release and merge. Also, thanks for catching those last minute fixes

NCAR / DART