Currently the users guide consists of LaTeX source files, and a manually compiled PDF stored in the repository. While this is not bad, moving to Sphinx RST format and setting up automated builds on ReadTheDocs.org (RTD) comes with many distinct advantages, and very few disadvantages. From my initial investigations, it seems like there shouldn't be any significant downsides to this conversion. The conversion can be automated using pandocs or a similar tool, and there is no possibility of incompatibility of existing LaTeX, since LaTeX can be embedded within Sphinx for anything that can't be handled natively in RST format. The only disadvantages seem to be one-time disadvantages that are far outweighed by the ongoing advantages advantages that will continue to payoff over time:
Advantages
Automated builds. I have personally had quite a pain getting the proper LaTeX tools set up on my new work computer (blame new IT protocols that don't allow me admin privileges), which wouldn't have been necessary if building the docs could be offloaded to RTD.
Easy public distribution. Currently the users guide is stored on Github, which does support the storing and viewing of PDFs in its code view, but it's a bit clunky. Additionally, the "official" users guide must be manually uploaded to the DTC website at each release. RTD allows easy support of release documentation tied to tags or branches, and allows the latest main branch documentation to be more easily accessible.
Multiple supported formats. LaTeX only easily converts to PDF files, which have advantages, but can be cumbersome in some contexts (especially on mobile devices). RTD easily supports both PDF and HTML automated builds.
No more storing binaries in the git repository. Git is not designed to store non-text files such as PDFs, and will balloon in size over time as more and more changes are tracked going forward.
Consistency with other UFS projects. RTD has become the de facto standard for documentation for the Unified Forecast System, being used for all public application releases and most individual application components (including the CCPP technical documentation). This will further build consistency to solidify the SCM as a vital part of the UFS ecosystem.
Disadvantages
Time/effort required. An initial time investment will be required to do the conversion, and anyone doing maintenance of the existing Users Guide who is not familiar with Sphinx will have a learning curve to deal with.
Other points
I did investigate the possibility of removing the PDF file from history, but I found that it did not substantially reduce the size of the repository (78MB --> 67MB), so it wouldn't be worth the disruption of a history rewrite in my opinion.
This comment will track features from the old users guide that are no longer available in the Sphinx format. This list should be small.
Different styles of code font for differentiating between terminal output and user input. This could be hacked in with CSS fonts/styles but I have chosen not to investigate solutions at this time since it is a minor concern for the most part
It turns out, full LaTeX embedding is not supported, only equations, so some original LaTeX fanciness (such as the directory tree in Chapter 3: Repository) needs to be worked around
Currently the users guide consists of LaTeX source files, and a manually compiled PDF stored in the repository. While this is not bad, moving to Sphinx RST format and setting up automated builds on ReadTheDocs.org (RTD) comes with many distinct advantages, and very few disadvantages. From my initial investigations, it seems like there shouldn't be any significant downsides to this conversion. The conversion can be automated using pandocs or a similar tool, and there is no possibility of incompatibility of existing LaTeX, since LaTeX can be embedded within Sphinx for anything that can't be handled natively in RST format. The only disadvantages seem to be one-time disadvantages that are far outweighed by the ongoing advantages advantages that will continue to payoff over time:
Advantages
Disadvantages
Other points
I did investigate the possibility of removing the PDF file from history, but I found that it did not substantially reduce the size of the repository (78MB --> 67MB), so it wouldn't be worth the disruption of a history rewrite in my opinion.