NCAR / ccpp-scm

CCPP Single Column Model
Other
13 stars 50 forks source link

Convert users guide to utilize ReadTheDocs #418

Closed mkavulich closed 3 months ago

mkavulich commented 7 months ago

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.

mkavulich commented 4 months ago

This comment will track features from the old users guide that are no longer available in the Sphinx format. This list should be small.