search

schism-dev / schism

Semi-implicit Cross-scale Hydroscience Integrated System Model (SCHISM)
http://ccrm.vims.edu/schismweb/
Apache License 2.0
87 stars 86 forks source link

📝 Online SCHISM documentation #62

Closed jamal919 closed 2 years ago

jamal919 commented 2 years ago

For quite some time, I have felt that the documentation of SCHISM does not get updated at the same pace as the SCHISM code-base itself. The codebase is evolving very rapidly, whereas the documentation is updated infrequently during a tagged version.

Since the SCHISM code has been moved fully to github, I believe it is timely to adopt a version-tracked documentation too by taking the advantage of github-pages. This is pretty common for github hosted software packages, and not uncommon for academic models either - for example, the Xbeach online documentation.

In this spirit, this work-in-progress repo is an initial configuration for a online documentation (hosted by github on github-pages). This allows a co-evolution of both the code and documentation, and both of those stays forever on github - fully version controlled. A live initial version based on mkdocs- which is continuously updated - can be browsed here.

I plan to first port the current pdf documentation - over next 4 months or so.

For now, I do not want this repo to be merged with the https://github.com/schism-dev/schism, but rather start a discussion with the user and developer community regarding viability and the structure of the docs. So the questions are -

My personal belief/opinion is that if the documentation gets real-time updates during the implementation of each future feature by the developer, it would be really helpful.

Opinion? (Browse current version here)

Progress checklist -

huyquangtranaus commented 2 years ago

Nice work mate. I wish I could contribute something with you and others 😊

A github.io webpage like Xbeach is very useful and nice.

Cheers Huy

On Tue, 1 Mar 2022 at 21:20, Jamal Uddin Khan @.***> wrote:

[Work-In-Progress] Not meant for merging yet, but only for discussions.

For quite some time, I have felt that the documentation of SCHISM does not get updated at the same pace as the SCHISM code-base itself. The codebase is evolving very rapidly, whereas the documentation is updated infrequently during a tagged version.

Since the SCHISM code has been moved fully to github, I believe it is timely to adopt a version-tracked documentation too by taking the advantage of github-pages. This is pretty common for github hosted software packages, and not uncommon for academic models either - for example, the Xbeach online documentation https://xbeach.readthedocs.io/en/latest/.

In this spirit, this work-in-progress repo is an initial configuration for a online documentation (hosted by github on github-pages). This allows a co-evolution of both the code and documentation, and both of those stays forever on github - fully version controlled. A live initial version based on mkdocs - without much content - can be browsed here https://jamalkhan.me/schism/.

I plan to first port the current pdf documentation - over next 4 months or so.

For now, I do not want this repo to be merged with the https://github.com/schism-dev/schism, but rather start a discussion with the user and developer community regarding viability and the structure of the docs. So the questions are -

  • Is keeping a online docs something interest the model users (and developers)?
  • Is it too much for the developers to update the documentation while developing a feature? In other words, is it viable to do so?
  • Any suggestion regarding the structure of the documentation?

My personal belief/opinion is that if the documentation gets real-time updates during the implementation of each future feature by the developer, it would be really helpful.

Opinion?

You can view, comment on, or merge this pull request online at:

https://github.com/schism-dev/schism/pull/62 Commit Summary

File Changes

(34 files https://github.com/schism-dev/schism/pull/62/files)

Patch Links:

— Reply to this email directly, view it on GitHub https://github.com/schism-dev/schism/pull/62, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHZU26KCPQLCYXDGOR3G6ALU5XVNLANCNFSM5PTTQLIA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you are subscribed to this thread.Message ID: @.***>

jamal919 commented 2 years ago

Thanks @huyquangtranaus, I appreciate your support. Please do not hesitate to add stuff, or suggest. It is written in markdown. The full file tree is here - https://github.com/jamal919/schism/tree/docs/docs

josephzhang8 commented 2 years ago

Hi Jamal:

First of all, thank you for spearheading this important effort. Documentation can be never enough or too frequent. Your proposed structure looks great to me.

I’m not sure about the effort level entailed. We want to make it as easy as possible if we are to make this sustainable in the long term. I’m interested in learning how to use the system and in particular, how easy is it to include graphics. I know Latex well and also html. Maybe the best way is for us to observe you updating the system as we learn once you merge it to main.

Thanks.

-Joseph

Y. Joseph Zhang Web: schism.wiki Office: 804 684 7466

From: Jamal Uddin Khan @.> Sent: Tuesday, March 1, 2022 5:20 AM To: schism-dev/schism @.> Cc: Subscribed @.***> Subject: [schism-dev/schism] 📝 [WIP] Online SCHISM documentation (PR #62)

[EXTERNAL to VIMS received message]

[Work-In-Progress] Not meant for merging yet, but only for discussions.

For quite some time, I have felt that the documentation of SCHISM does not get updated at the same pace as the SCHISM code-base itself. The codebase is evolving very rapidly, whereas the documentation is updated infrequently during a tagged version.

Since the SCHISM code has been moved fully to github, I believe it is timely to adopt a version-tracked documentation too by taking the advantage of github-pages. This is pretty common for github hosted software packages, and not uncommon for academic models either - for example, the Xbeach online documentationhttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fxbeach.readthedocs.io%2Fen%2Flatest%2F&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098505665%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=aBFuOsiXDVI9Y9LsPipqmk%2BDAQBZpkUQxn1utXZNlKo%3D&reserved=0.

In this spirit, this work-in-progress repo is an initial configuration for a online documentation (hosted by github on github-pages). This allows a co-evolution of both the code and documentation, and both of those stays forever on github - fully version controlled. A live initial version based on mkdocs - without much content - can be browsed herehttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fjamalkhan.me%2Fschism%2F&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098505665%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=MSVH65RT6A7wweXV4FWJy%2F6bbyQUyC306UBMR9leUt4%3D&reserved=0.

I plan to first port the current pdf documentation - over next 4 months or so.

For now, I do not want this repo to be merged with the https://github.com/schism-dev/schismhttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fschism-dev%2Fschism&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098505665%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=fp4GBt9PGUQW2F4fzZS2uru3d04hXQr0XRScioJ8ZU4%3D&reserved=0, but rather start a discussion with the user and developer community regarding viability and the structure of the docs. So the questions are -

My personal belief/opinion is that if the documentation gets real-time updates during the implementation of each future feature by the developer, it would be really helpful.

Opinion?

You can view, comment on, or merge this pull request online at:

https://github.com/schism-dev/schism/pull/62https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fschism-dev%2Fschism%2Fpull%2F62&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098505665%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=ZUB0G2nNGweULqBzJy8koM9oiFrcp3MjaGdGRXnHJew%3D&reserved=0

Commit Summary

File Changes

(34 fileshttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fschism-dev%2Fschism%2Fpull%2F62%2Ffiles&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098662506%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=BmI8WJLh8fxMD9%2BpIfbnvLNqetvamXQbeshgQQYzOms%3D&reserved=0)

Patch Links:

— Reply to this email directly, view it on GitHubhttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fschism-dev%2Fschism%2Fpull%2F62&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098818097%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=NMcEMmfkKqG8FiL3Be2zjc8AJXGEFhIzONmsBkFIz3E%3D&reserved=0, or unsubscribehttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAFBKNZ4WOP4WWHEDWP73MSTU5XVNLANCNFSM5PTTQLIA&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098818097%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=Yutoj9ZgQ3NO0Pkj0EmChzs%2F6AA%2BRATeXVeTrGyFGII%3D&reserved=0. Triage notifications on the go with GitHub Mobile for iOShttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapps.apple.com%2Fapp%2Fapple-store%2Fid1477376905%3Fct%3Dnotification-email%26mt%3D8%26pt%3D524675&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098818097%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=IJxVbFAgVpzqbNQFKNFU%2Fx%2B8inI64keUYUVxDPY2PLk%3D&reserved=0 or Androidhttps://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fplay.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.github.android%26referrer%3Dutm_campaign%253Dnotification-email%2526utm_medium%253Demail%2526utm_source%253Dgithub&data=04%7C01%7Cyjzhang%40vims.edu%7C07d78d333bea464dd88308d9fb6d0e53%7C8cbcddd9588d4e3b9c1e2367dbdf1740%7C0%7C1%7C637817268098818097%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=gQLbHCeNijaehtLqkHT0%2BG5Blfrh2qnRS8PxVY%2BYdVE%3D&reserved=0. You are receiving this because you are subscribed to this thread.Message ID: @.**@.>>

jamal919 commented 2 years ago

Thanks Joseph,

I’m not sure about the effort level entailed. We want to make it as easy as possible if we are to make this sustainable in the long term. I’m interested in learning how to use the system and in particular, how easy is it to include graphics.

Good question.

Effort: The effort required is very minimum. The individual files are written in github markdown - which most of us already know.

Structure: The structure of the documentation is defined in mkdocs.yml file (as a toc). This we can do once, and go long way before changing anything. At the same time it is very flexible. By simply changing the mkdocs.yml the whole structure can be changed quickly.

Image: Images are added like in markdown ![](path/to/image) or html <figure>/<img> tag. I have in my agenda to add extra css for it to add auto numbering of the captions. Currently I have set up the structure to have all the images in the assets folder.

Math: I have configured mathjx, which allows equations to be written as latex \begin{equation}...\end{equation} or $ ... $ tags.

The final site gets generated from these set of individual markdown files by mkdocs. So with mkdocs installed (using python pip) one can look at the generated docs locally. On the other hand, I have setup a github action to generate the docs and publish the site automatically for each push to the repository. Additionally, a PDF for the whole doc can also be auto-generated and linked.

Maybe the best way is for us to observe you updating the system as we learn once you merge it to main.

That makes sense. I will keep the progress updated here.

josephzhang8 commented 2 years ago

Sounds like a very powerful. I look forward to seeing it in action; thx, Jamal!

-Joseph

Y. Joseph Zhang Web: schism.wiki Office: 804 684 7466

From: Jamal Uddin Khan @.> Sent: Wednesday, March 2, 2022 8:48 AM To: schism-dev/schism @.> Cc: Y. Joseph Zhang @.>; Comment @.> Subject: Re: [schism-dev/schism] 📝 [WIP] Online SCHISM documentation (PR #62)

[EXTERNAL to VIMS received message]

Thanks Joseph,

I’m not sure about the effort level entailed. We want to make it as easy as possible if we are to make this sustainable in the long term. I’m interested in learning how to use the system and in particular, how easy is it to include graphics.

Good question.

Effort: The effort required is very minimum. The individual files are written in github markdown - which most of us already know.

Structure: The structure of the documentation is defined in mkdocs.yml file (as a toc). This we can do once, and go long way before changing anything. At the same time it is very flexible. By simply changing the mkdocs.yml the whole structure can be changed quickly.

Image: Images are added like in markdown [X] <path/to/image> or html / tag. I have in my agenda to add extra css for it to add auto numbering of the captions. Currently I have set up the structure to have all the images in the assets folder.

Math: I have configured mathjx, which allows equations to be written as latex \begin{equation}...\end{equation} or $ ... $ tags.

The final site gets generated from these set of individual markdown files by mkdocs. So with mkdocs installed (using python pip) one can look at the generated docs locally. On the other hand, I have setup a github action to generate the docs and publish the site automatically for each push to the repository. Additionally, a PDF for the whole doc can also be auto-generated and linked.

Maybe the best way is for us to observe you updating the system as we learn once you merge it to main.

That makes sense. I will keep the progress updated here.

— Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you commented.Message ID: @.***>

feiye-vims commented 2 years ago

@jamal919 Great work! I think this is the way to go for documentation. I'm very interested in observing your progress and contributing to it.

@josephzhang8 I can confirm the effort needed for maintaining this kind of webpage is not too much. But the initial effort (e.g., converting the manual to markdown format) can take some time. I'm grateful for having colleagues like Jamal, who takes time to start the work.

@josephzhang8 and @jamal919 We did have some requests for this kind of webpage from the participants of past workshops (e.g., the compound flooding tutorial we gave through NOAA's venue). As a response to those requests, we set up a webpage for case studies, utility scripts, and other miscellaneous topics here: schism-tut. It probably fits into the "case study" section of Jamal's more expansive doc. I guess we can merge our existing pages into Jamal's at some point.

josephzhang8 commented 2 years ago

Many thanks, Jamal!

josephzhang8 commented 2 years ago

Hi Jamal:

The merge button is dimmed so I think u need to submit a final PR. Thx

jamal919 commented 2 years ago

Hi Joseph,

Yes, I have put the PR in WIP (draft mode), as most of the sections are currently empty and I am working on the porting. I will activate it for a PR once the first usable version is ready. I will then request you as the reviewer and you can then approve and merge it to the main branch. We will also have to activate the github-page option in the repo at that time. Thanks.

jamal919 commented 2 years ago

Hi @feiye-vims,

Thanks for sharing the schism-tut - quite a nice tutorial page. The content of the schism-tut is a nice fit to go into case-study, and definitely should be linked to the docs. I have already ported over the verification test-page to the docs. I hope it does not conflict with the license of the content.

feiye-vims commented 2 years ago

Hi @feiye-vims,

Thanks for sharing the schism-tut - quite a nice tutorial page. The content of the schism-tut is a nice fit to go into case-study, and definitely should be linked to the docs. I have already ported over the verification test-page to the docs. I hope it does not conflict with the license of the content.

Feel free to port anything over. I'll check the license and make sure there is no conflict with it. We can talk later on when is the good time to merge the entire schism-tut to the full doc.

Best! Fei