blaylockbk
New member
The online MPAS-Atmosphere User Guide is extremely useful. Since you are always asking for feedback, I wanted to share a suggestion to make the pages even better. Would you consider using a different static site generator?
The current site is written in restructured text and uses the TYPO3 4.9 Sphinx theme. There are a few issues with this theme:
It may be possible to address these issues by switching to a more modern and maintained Sphinx theme.
Alternatively, you might consider a Markdown-based static site generator such as MkDocs. In my experience, Markdown is often easier to work with, and tools like Material for MkDocs produce clean, responsive documentation sites. The NCAR HPC docs are generated using the very popular Material for MkDocs. I'll note that the Materical for MkDocs theme was recently retired in favor of the new Zensical static site generator. I actually put the MPAS tutorial's raw HTML through an LLM, converted it to markdown pages, and built a site with Zensical, which turned out very nice.
As a side note, I may be looking in the wrong place, but are the user guide and tutorial sources hosted on GitHub? I found a couple of repositories (this and this) but they didn’t appear to contain the full documentation source.
Thanks for your consideration, and thanks for the wonderful docs you provide! They really make MPAS easier to use.
The current site is written in restructured text and uses the TYPO3 4.9 Sphinx theme. There are a few issues with this theme:
- The TYPO3 theme is unmaintained. It hasn't had any commits in 3 years, and the GitHub repo was recently archived.
- The search feature seems limited (e.g., exact matches), which can make it difficult to find relevant results.
- Cosmetic: The navigation menu can overflow the page when expanded.
- Cosmetic: The site is not responsive, which makes it difficult to use on mobile devices. I like to browse docs on my phone when I'm on the go or sitting on the couch.
It may be possible to address these issues by switching to a more modern and maintained Sphinx theme.
Alternatively, you might consider a Markdown-based static site generator such as MkDocs. In my experience, Markdown is often easier to work with, and tools like Material for MkDocs produce clean, responsive documentation sites. The NCAR HPC docs are generated using the very popular Material for MkDocs. I'll note that the Materical for MkDocs theme was recently retired in favor of the new Zensical static site generator. I actually put the MPAS tutorial's raw HTML through an LLM, converted it to markdown pages, and built a site with Zensical, which turned out very nice.
As a side note, I may be looking in the wrong place, but are the user guide and tutorial sources hosted on GitHub? I found a couple of repositories (this and this) but they didn’t appear to contain the full documentation source.
Thanks for your consideration, and thanks for the wonderful docs you provide! They really make MPAS easier to use.