search

NGEET / fates

repository for the Functionally Assembled Terrestrial Ecosystem Simulator (FATES)
Other
96 stars 91 forks source link

user experience improvements #830

Closed rgknox closed 1 year ago

rgknox commented 2 years ago

Discussions at the CLM land-model group, Jan 27 2022, generating ideas about improving user experience. Feel free to add ideas on this thread:

Lets create a Quick-start Guide

Lets create a Searchable User's Guide

KatieMurenbeeld commented 2 years ago

Something that links the equations/text to the parameters in the .F90 files.

glemieux commented 2 years ago

Include a "Noteworthy Differences" page comparing the differences between big-leaf clm and fates as part of the FAQ, akin to this: https://docs.julialang.org/en/v1/manual/noteworthy-differences/.

glemieux commented 2 years ago

Something that links the equations/text to the parameters in the .F90 files.

I wonder if there is a package out there that will parse for docstrings in fortran :thinking:. Does sphinx or doxygen have their own package extensions?

EDIT: https://sphinx-fortran.readthedocs.io/en/latest/user.autodoc.html looks promising

glemieux commented 2 years ago

Ok, here's a first crack at converting the wiki pages into a standard readthedocs (rtd) format: https://fates-users-guide.readthedocs.io/en/latest/index.html#

This took me about 6 hours total to pull together. It only includes the 2019 tutorial and the faq in the user's guide section and the style guide in the developer's guide section so far. A bunch of that was fussing around with rtd, but reformatting for the restructuredtext to a good chunk of time too. Please take a look and let me know if this looks promising before I spend more time on it.

Note that its currently hosted on my personal github account and my personal rtd account, hence the side bar ads. If people think this looks worthwhile, I'll migrate it over to the NGEET org github and rtd accounts.