Moving documentation to ReadTheDocs

NCAR / ccpp-scm

CCPP Single Column Model

Other

13 stars 50 forks source link

Moving documentation to ReadTheDocs #438

Closed mkavulich closed 3 months ago

mkavulich commented 4 months ago

This PR removes the old, LaTeX-based users guide in favor of RST files that are buildable with Sphinx. These new docs have been configured to automatically build with each commit to main on ReadTheDocs, and can be viewed here: html | PDF

For limitations in the new docs compared to the previous LaTeX/PDF, see this comment

NOTE: The original LaTeX files were auto-converted from .tex to .rst using the pandoc utility, and then manually updated for format. The conversion was not perfect: in particular, most section/chapter links were broken, and all code-case text was omitted from the converted docs. These problems needed to be fixed manually, but it's entirely possible some of these may have slipped into the final product.

Resolves #418

scrasmussen commented 4 months ago

@mkavulich this looks really great! I checked out the branch to add documentation for the single precision build and it was easy to use and worked well. A few comments:

with the move away from LaTeX it seems the Makefile should be updated or deleted?
I don't know if would be helpful if there was a small section in the documentation to tell users how to build the readthedocs locally or if it should be a README.md under scm/doc/TechGuide? Apologies if this information is already in the docs somewhere. I installed the requirements and then ended up googling the command $ sphinx-build -M html [source_dir] [output_dir]
should the chap_function.rst file be named chap_algorithm.rst since it is the Algorithm chapter?

Anyway, these are just small things, overall it worked very well for me!

mkavulich commented 4 months ago

@scrasmussen Thanks for the review! I have updated the Makefile, though I am unable to test the latex/pdf rule because I can not install latexmk on my machine (which is part of why this whole conversation of moving to ReadTheDocs started!). I also added a README.md file to assist people who are interested in building the HTML or PDF documentation.

With regards to renaming documents/chapters, I kept the names from the original .tex files. I would rather keep the format-transition commits contained here and make any other cleanup in subsequent PRs.

grantfirl commented 3 months ago

I didn't review in detail, although, in general, it looks great. Although I love LaTeX, this is a better way to format software docs in pretty much every way. Thanks for doing this.