Moving documentation to ReadTheDocs (NCAR#438)

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: https://ccpp-scm.readthedocs.io/en/latest/

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: scm/doc/TechGuide/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - htmlzip
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: scm/doc/TechGuide/requirements.txt

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2022, NOAA, UCAR/NCAR, CU/CIRES, CSU/CIRA 
+Copyright 2024, NOAA, UCAR/NCAR, CU/CIRES, CSU/CIRA 
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -10,4 +10,4 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-limitations under the License.
+limitations under the License.

README.md

@@ -1,3 +1,3 @@
 # User's Guide
 
-Please find the up-to-date User's Guide located in this repository in [`scm/doc/TechGuide/main.pdf`](https://github.com/NCAR/ccpp-scm/blob/main/scm/doc/TechGuide/main.pdf)
+Please find the up-to-date User's Guide located on ReadTheDocs: https://ccpp-scm.readthedocs.io/en/latest/

scm/doc/README.md

@@ -0,0 +1,17 @@
+# SCM documentation
+
+The SCM technical documentation/users' guide is written in [reStructured Text markup language (RST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). It is designed to be built with the [Sphinx documentation tool](https://www.sphinx-doc.org/en/master/index.html), and is documentation from the `main` branch is configured to build automatically on ReadTheDocs: https://ccpp-scm.readthedocs.io/en/latest/
+
+## Building docs locally
+
+To build the HTML documentation locally (for example, when testing modifications to the documentation), you must have Sphinx [installed on your machine](https://www.sphinx-doc.org/en/master/usage/installation.html), as well as the required python packages listed in the `requirements.txt` file. Once the prerequisite software is installed, you can build the HTML documentation using the following commands:
+
+    python -m sphinx -T -b html -d _build/doctrees -D language=en . html
+
+To build a PDF locally, in addition to Sphinx you must have Perl as well as the Perl-based [`latexmk` utility](https://mg.readthedocs.io/latexmk.html#installation). You can then build a PDF using the following commands:
+
+    python -m sphinx -T -b latex -d _build/doctrees -D language=en . latex
+    latexmk -f -pdf -pdflatex="pdflatex" -use-make index.tex
+
+In lieu of running the above commands manually, you can also use `make`. The command `make all` will build both HTML and PDF documentation, while `make html` and `make latex` will build HTML and PDF respectively.
+

scm/doc/TechGuide/Makefile

@@ -2,13 +2,16 @@
 # Makefile for the CCPP (SCM) Users Guide
 #
 
-.PHONY: main.pdf all clean
+.PHONY: html latex all clean
 
-all: main.pdf
+all: html latex
 
-main.pdf: main.tex
-	latexmk -f -pdf -pdflatex="pdflatex" -use-make main.tex
-	open main.pdf
+latex:
+	python -m sphinx -T -b latex -d _build/doctrees -D language=en . latex
+	cd latex && latexmk -f -pdf -pdflatex="pdflatex" -use-make index.tex
+
+html:
+	python -m sphinx -T -b html -d _build/doctrees -D language=en . html
 
 clean:
 	latexmk -CA

scm/doc/TechGuide/acknow.rst

@@ -0,0 +1,12 @@
+Acknowledgement
+===============
+If significant help was provided via the helpdesk, email, or
+support forum for work resulting in a publication, please
+acknowledge the Developmental Testbed Center team.
+
+For referencing this document please use:
+
+      Firl, G., D. Swales, L. Carson, L. Bernardet, D. Heinzeller, M. Harrold, T. Hertneky, and
+      M. Kavulich, 2024. Common Community Physics Package Single Column Model v7.0.0 User and
+      Technical Guide. Available at https://ccpp-scm.readthedocs.io/en/latest/.
+