Merge pull request #21 from PecanProject/doxygen

Update Doxygen and Makefile

Author: dlebauer

.github/workflows/ci.yml

@@ -25,7 +25,16 @@ jobs:
     # checkout source code
     - uses: actions/checkout@v2
 
-    # compile sipnet
+    # install doxygen
+    - name: Install Doxygen
+      run:  |
+        if [[ "$RUNNER_OS" == "Linux" ]]; then
+          sudo apt-get install doxygen -y
+        elif [[ "$RUNNER_OS" == "macOS" ]]; then
+          brew install --formula doxygen
+        fi
+        
+    # compile SIPNET
     - name: compile sipnet
       run: make
 

.gitignore

@@ -1,5 +1,25 @@
+# build artifacts and executables
 *.o
 estimate
 sipnet
 subsetData
 transpose
+.doxygen.stamp
+
+# documentation
+docs/html
+docs/latex
+
+.DS_Store
+.Rproj.user
+.Rhistory
+
+# System-specific files
+.DS_Store
+.Rproj.user
+.Rhistory
+
+# Temporary and backup files
+*.bak
+*~
+*.tmp

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+
+## Style Guide
+
+## Compiling
+
+SIPNET uses `make` to build the model and documentation. There are also miscellaneous targets for running analysis workflows:
+
+```sh
+# build SIPNET executable
+make sipnet
+# build documentation
+make document
+# clean up build artifacts
+make clean
+# list all make commands
+make help
+```

Makefile

@@ -18,8 +18,27 @@ TRANSPOSE_OFILES=$(TRANSPOSE_CFILES:.c=.o)
 SUBSET_DATA_CFILES=subsetData.c util.c namelistInput.c
 SUBSET_DATA_OFILES=$(SUBSET_DATA_CFILES:.c=.o)
 
+CFILES=$(sort $(ESTIMATE_CFILES) $(SENSTEST_CFILES) $(SIPNET_CFILES) $(TRANSPOSE_CFILES) $(SUBSET_DATA_CFILES))
+
+# Doxygen
+DOXYFILE = docs/Doxyfile
+DOXYGEN_HTML_DIR = docs/html
+DOXYGEN_LATEX_DIR = docs/latex
+
+# .PHONY indicates target names that are not file names, preventing conflicts if these names are used for filenames
+.PHONY: all clean document estimate sipnet transpose subsetData doxygen
+
 # all: estimate sensTest sipnet transpose subsetData
-all: estimate sipnet transpose subsetData
+all: estimate sipnet transpose subsetData document
+
+
+# Only update docs if source files or Doxyfile have changed
+document: .doxygen.stamp
+
+.doxygen.stamp: $(CFILES) $(DOXYFILE)
+	@echo "Running Doxygen..."
+	doxygen $(DOXYFILE)
+	@touch .doxygen.stamp
 
 estimate: $(ESTIMATE_OFILES)
 	$(LD) -o estimate $(ESTIMATE_OFILES) $(LIBLINKS)
@@ -38,14 +57,27 @@ subsetData: $(SUBSET_DATA_OFILES)
 
 clean:
 	rm -f $(ESTIMATE_OFILES) $(SIPNET_OFILES) $(TRANSPOSE_OFILES) $(SUBSET_DATA_OFILES) estimate sensTest  sipnet transpose subsetData
-
+	rm -rf $(DOXYGEN_HTML_DIR) $(DOXYGEN_LATEX_DIR)
 #clean:
 #	rm -f $(ESTIMATE_OFILES) $(SENSTEST_OFILES) $(SIPNET_OFILES) $(TRANSPOSE_OFILES) $(SUBSET_DATA_OFILES) estimate sensTest  sipnet transpose subsetData
 
+help:
+	@echo "Available targets:"
+	@echo "  help        - Display this help message."
+	@echo "  === core targets ==="
+	@echo "  all         - Builds all components."
+	@echo "  document    - Generate documentation."
+	@echo "  sipnet      - Builds the 'sipnet' executable."
+	@echo "  clean       - Removes compiled files, executables, and documentation."
+	@echo "  depend      - Automatically generates dependency information for source files."
+	@echo "  === additional tools ==="
+	@echo "  estimate    - Builds 'estimate' executable to estimate parameters using MCMC."
+	@echo "  transpose   - Builds 'transpose' executable to read in and transpose a matrix"
+	@echo "  subsetData  - Builds 'subsetData' executable that subsets input files (e.g., .clim, .dat, .valid, .sigma, .spd) from a specified start date and length of time in days."
 
-#This target automatically builds dependencies.
 depend::
 	makedepend $(CFILES)
 
 # DO NOT DELETE THIS LINE -- make depend depends on it.
 
+

docs/Doxyfile

@@ -5,8 +5,8 @@
 #---------------------------------------------------------------------------
 PROJECT_NAME           = SIPNET
 PROJECT_NUMBER         = 1.0
-OUTPUT_DIRECTORY       = /Users/aulenbac/Documents/workspace/SIPNET/docs
-CREATE_SUBDIRS         = NO
+OUTPUT_DIRECTORY       = docs
+CREATE_SUBDIRS         = YES
 OUTPUT_LANGUAGE        = English
 USE_WINDOWS_ENCODING   = NO
 BRIEF_MEMBER_DESC      = YES
@@ -24,8 +24,8 @@ ABBREVIATE_BRIEF       = "The $name class" \
                          the
 ALWAYS_DETAILED_SEC    = NO
 INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        = /Applications/
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = ../..
 STRIP_FROM_INC_PATH    = 
 SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = NO
@@ -82,7 +82,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = /Users/aulenbac/Documents/workspace/SIPNET
+INPUT                  = ../
 FILE_PATTERNS          = *.c \
                          *.cc \
                          *.cxx \