Merge branch 'develop' into fix_pre-built-sipnet

CHANGELOG.md

@@ -9,6 +9,9 @@ For more information about this file see also [Keep a Changelog](http://keepacha
 
 ### Added
 
+- Documentation of `make` options including addition of `make help` 
+- Add make option to document a single package with `make documentation pathto/package` 
+
 ### Fixed
 - updated github action to build docker images
 - PEcAn.SIPNET now accepts relative paths in its input XML (#3418). Previously all files referenced in the autogenerated `job.sh` needed to be specified as absolute paths.

Makefile

@@ -10,10 +10,10 @@ MODULES := allometry assim.batch assim.sequential benchmark \
 				 emulator meta.analysis \
 				 photosynthesis priors rtm uncertainty
 
-# Components not currently included in the build
-# (Most need more development first)
-# 	models: cable
-#	modules: data.mining, DART
+## Components not currently included in the build
+## (Most need more development first)
+## 	models: cable
+##	modules: data.mining, DART
 
 SHINY := $(dir $(wildcard shiny/*/.))
 SHINY := $(SHINY:%/=%)
@@ -99,36 +99,64 @@ doc_R_pkg = \
 
 depends = .doc/$(1) .install/$(1) .check/$(1) .test/$(1)
 
-
 ### Rules
 
 .PHONY: all install check test document shiny \
             check_base check_models check_modules 
 
-all: install document
-
+all: install document ## Install all packages and generate documentation
 
-check_base: $(BASE_C) 
-check_models: $(MODELS_C) 
+check_base: $(BASE_C)     ## Check base packages  
+check_models: $(MODELS_C) ## Check model packages   
 
 # Install base first as Modules has a circular dependency on base,
 # and then run a check on modules
-check_modules: $(BASE_I) $(MODULES_C) 
+check_modules: $(BASE_I) $(MODULES_C) ## Install base packages, check module packages
+
+.PHONY: document
+document: ## Generate documentation for all packages or a single package: make document path/to-package
+	@if [ "$(filter-out $@,$(MAKECMDGOALS))" ]; then \
+		PKG="$(filter-out $@,$(MAKECMDGOALS))"; \
+		echo "Documenting package: $$PKG"; \
+		$(call doc_R_pkg, $$PKG); \
+	else \
+		echo "Documenting all packages"; \
+		$(MAKE) $(ALL_PKGS_D) .doc/base/all; \
+	fi
 
-document: $(ALL_PKGS_D) .doc/base/all
-install: $(ALL_PKGS_I) .install/base/all
-check: $(ALL_PKGS_C) .check/base/all
-test: $(ALL_PKGS_T) .test/base/all
-shiny: $(SHINY_I)
+install: $(ALL_PKGS_I) .install/base/all ## Install all packages
+check: $(ALL_PKGS_C) .check/base/all     ## Check all packages
+test: $(ALL_PKGS_T) .test/base/all       ## Test all packages
+shiny: $(SHINY_I)                        ## Install Shiny app dependencies
 
-# Render the PEcAn bookdown documentation
-book:
-	cd ./book_source && make build
+
+book: 
+	cd ./book_source && make build ## Render the PEcAn bookdown documentation
 
 # Make the timestamp directories if they don't exist yet
 .doc .install .check .test .shiny_depends $(call depends,base) $(call depends,models) $(call depends,modules):
 	mkdir -p $@
 
+### Help
+
+help: ## Show this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Examples:"
+	@echo "  make all     "
+	@echo "  make document"
+	@echo "  make document modules/assim.sequential  # Generate documentation for a specific package"
+	@echo ""
+	@echo "Notes:"
+	@echo "  - Components not included: cable (models), data.mining and DART (modules)."
+	@echo "  - Standard workflow: install packages, run checks, test, and document before submitting a PR."
+	@echo "  - Before submitting a PR, please ensure that all tests pass, code is linted, and documentation is up-to-date."
+	@echo ""
+	@echo "Available targets:"
+	@grep -h -E '^[a-zA-Z0-9_-]+:.*?## ' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-20s %s\n", $$1, $$2}'
+
+
 ### Dependencies
 
 # models import Roxygen docs from *installed* version of template,
@@ -140,10 +168,11 @@ $(subst .doc/models/template,,$(MODELS_D)): .install/models/template
 # target need not be rebuilt when a prerequisite changes)
 include Makefile.depends
 
-clean:
+.PHONY: clean
+clean: 
 	rm -rf .install .check .test .doc
 	find modules/rtm/src \( -name \*.mod -o -name \*.o -o -name \*.so \) -delete
-	find models/basgra/src \( -name \*.mod -o -name \*.o -o -name \*.so \) -delete
+	find models/basgra/src \( -name \*.mod -o -name \*.o -o -name \*.so \) -delete ## Clean build artifacts.
 
 .install/devtools: | .install
 	+ ./scripts/time.sh "devtools ${1}" Rscript -e ${SETROPTIONS} -e "if(!requireNamespace('devtools', quietly = TRUE)) install.packages('devtools')"

base/settings/tests/Rcheck_reference.log

@@ -121,14 +121,7 @@ manual.
 The argument of a replacement function which corresponds to the right
 hand side must be named ‘value’.
 * checking foreign function calls ... OK
-* checking R code for possible problems ... NOTE
-check.ensemble.settings: no visible binding for global variable
-  ‘startdate’
-check.ensemble.settings: no visible binding for global variable
-  ‘enddate’
-site.pft.link.settings: no visible binding for global variable ‘.’
-Undefined global functions or variables:
-  . enddate startdate
+* checking R code for possible problems ... OK
 * checking Rd files ... OK
 * checking Rd metadata ... OK
 * checking Rd line widths ... OK

book_source/02_demos_tutorials_workflows/05_developer_workflows/01_update_pecan_code.Rmd

@@ -20,6 +20,8 @@ This will update the documentation for all packages and install them, as well as
 
 For more control, the following `make` commands are available:
 
+* `make help` -- shows all available make options.
+
 * `make document` -- Use `devtools::document` to update the documentation for all package. 
 Under the hood, this uses the `roxygen2` documentation system.