diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c2880ac..20106891 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 432de27a..757dc24a 100644 --- a/.gitignore +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7806eda2 --- /dev/null +++ b/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 +``` diff --git a/Makefile b/Makefile index 200df75d..e47457e2 100755 --- a/Makefile +++ b/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. + diff --git a/docs/Doxyfile b/docs/Doxyfile index bb222159..19863768 100644 --- a/docs/Doxyfile +++ b/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 \