From 09c0e5f30883f3bdda48462d182676bcd0a67f87 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Sun, 23 Jan 2022 09:28:25 -0500 Subject: [PATCH 01/17] github actions: add g++ for cygwin - the development should have been on a dedicated branch instead of on master since the start ...! - add g++ for cygwin build --- .github/workflows/main.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f404b874c..c76b1f7d0 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -10,6 +10,7 @@ on: pull_request: branches: - master + - feature_ghactions_v2 jobs: build: @@ -81,7 +82,7 @@ jobs: - name: Install cygwin (windows) uses: cygwin/cygwin-install-action@v1 with: - packages: gcc-core make + packages: gcc-core gcc-g++ make - name: Print compiler versions as seen by make run: make compiler_version From 59e148616753925be6423dda6ecb6ccc227b446b Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Sun, 23 Jan 2022 09:50:34 -0500 Subject: [PATCH 02/17] Fix compiler "Warning: array subscript has type char" - warning was issued on github actions for a build on windows-release with cygwin and gcc v11.2.0 - the argument of `isalpha()` is "int ch" (https://en.cppreference.com/w/c/string/byte/isalpha) but we were passing in a "char" (which may be signed or unsigned depending on platform and compiler) - similarly to the use in the next line with `toupper()`, the fix is to convert to "int" --- SW_Model.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SW_Model.c b/SW_Model.c index 8cd1d6d65..bffaf0d6c 100644 --- a/SW_Model.c +++ b/SW_Model.c @@ -166,7 +166,7 @@ void SW_MDL_read(void) { cnt = 0; while (GetALine(f, inbuf)) { cnt++; - if (isalpha(*inbuf) && strcmp(inbuf, "end")) { /* get hemisphere */ + if (isalpha((int) *inbuf) && strcmp(inbuf, "end")) { /* get hemisphere */ m->isnorth = (Bool) (toupper((int) *inbuf) == 'N'); fhemi = swTRUE; break; From 968e7e6a9cac37e932711751349cb3b649881ff0 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 08:34:25 -0500 Subject: [PATCH 03/17] github actions: no saniziters on cygwin AddressSanitizer and LeakSanitizer are not available on cygwin (https://github.com/google/sanitizers, but see https://github.com/google/sanitizers/wiki/AddressSanitizerWindowsPort) --- .github/workflows/main.yml | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c76b1f7d0..b1799e938 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -26,10 +26,10 @@ jobs: uses: actions/checkout@v2 with: submodules: recursive - + - name: Print compiler versions as seen by make run: make compiler_version - + - name: Run binary run: | make clean bin bint_run @@ -37,16 +37,16 @@ jobs: - name: Unit tests run: make clean test test_run - + - name: Severe unit tests (without sanitizers) if: ${{ runner.os == 'macOS' }} run: make clean test_severe test_run - + - name: Severe unit tests (with sanitizers) # Apple clang does not support "AddressSanitizer: detect_leaks" (at least as of clang-1200.0.32.29) if: ${{ runner.os != 'macOS' }} run: ASAN_OPTIONS=detect_leaks=1:strict_string_checks=1:detect_stack_use_after_return=1:check_initialization_order=1:strict_init_order=1 LSAN_OPTIONS=suppressions=.LSAN_suppr.txt make clean test_severe test_run - + - name: Generate coverage report (ubuntu) if: ${{ runner.os == 'Linux' && success() }} run: make clean cov cov_run @@ -56,12 +56,12 @@ jobs: uses: codecov/codecov-action@v2 with: fail_ci_if_error: false # just report, don't fail checks - - + + build_Windows_Cygwin: # see https://github.com/cygwin/cygwin-install-action # based on https://github.com/resurrecting-open-source-projects/scrot - + runs-on: windows-latest env: CYGWIN_NOWINPATH: 1 # only have cygwin's executables on PATH @@ -78,22 +78,18 @@ jobs: uses: actions/checkout@v2 with: submodules: recursive - + - name: Install cygwin (windows) uses: cygwin/cygwin-install-action@v1 with: packages: gcc-core gcc-g++ make - + - name: Print compiler versions as seen by make run: make compiler_version - + + # AddressSanitizer and LeakSanitizer not available on cygwin - name: Run binary - run: | - make clean bin bint_run - make clean bin_debug_severe bint_run + run: make clean bin bint_run - name: Unit tests run: make clean test test_run - - - name: Severe unit tests (without sanitizers) - run: make clean test_severe test_run From ec65df423e0b5965bac9e9c617ebae87c3c8e564 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 08:42:03 -0500 Subject: [PATCH 04/17] github actions: clean up script --- .github/workflows/main.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b1799e938..5e7aaefb2 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -10,7 +10,6 @@ on: pull_request: branches: - master - - feature_ghactions_v2 jobs: build: From b04333043e72489df24c87899a4bae59c512a8f8 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 09:10:58 -0500 Subject: [PATCH 05/17] github actions: check documentation - new step "check_documentation" (only on linux): install doxygen, build SOILWAT2 documentation, and check that no unexpected warnings occurred - also: re-organized code coverage checks as separate job --- .github/workflows/main.yml | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5e7aaefb2..45dc1c693 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,7 +1,6 @@ name: SOILWAT2 C/C++ CI -#TODO: add gcc and clang versions -#TODO: add doxygen documentation check +#TODO: run unit tests with different compiler versions of both gcc and clang on: push: @@ -12,7 +11,7 @@ on: - master jobs: - build: + build_nix: strategy: fail-fast: false @@ -46,17 +45,34 @@ jobs: if: ${{ runner.os != 'macOS' }} run: ASAN_OPTIONS=detect_leaks=1:strict_string_checks=1:detect_stack_use_after_return=1:check_initialization_order=1:strict_init_order=1 LSAN_OPTIONS=suppressions=.LSAN_suppr.txt make clean test_severe test_run - - name: Generate coverage report (ubuntu) - if: ${{ runner.os == 'Linux' && success() }} + + check_code_coverage: + runs-on: ubuntu-latest + needs: build_nix + + steps: + - name: Generate coverage report run: make clean cov cov_run - - name: Upload coverage to Codecov (ubuntu) - if: ${{ runner.os == 'Linux' && success() }} + - name: Upload coverage to Codecov uses: codecov/codecov-action@v2 with: fail_ci_if_error: false # just report, don't fail checks + check_documentation: + runs-on: ubuntu-latest + needs: build_nix + + steps: + - name: Install doxygen + run: | + sudo apt-get update + sudo apt-get install doxygen + - name: Build documentation and check for warnings + run: make doc + + build_Windows_Cygwin: # see https://github.com/cygwin/cygwin-install-action # based on https://github.com/resurrecting-open-source-projects/scrot From a5b215412d9f1b20ab2a62b771069515d15db318 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 09:17:53 -0500 Subject: [PATCH 06/17] github actions: fix separate jobs - each job needs to check out the repository --- .github/workflows/main.yml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 45dc1c693..f539a8e1d 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -48,9 +48,13 @@ jobs: check_code_coverage: runs-on: ubuntu-latest - needs: build_nix steps: + - name: Checkout repository and submodules + uses: actions/checkout@v2 + with: + submodules: recursive + - name: Generate coverage report run: make clean cov cov_run @@ -62,15 +66,20 @@ jobs: check_documentation: runs-on: ubuntu-latest - needs: build_nix - + steps: + - name: Checkout repository and submodules + uses: actions/checkout@v2 + with: + submodules: recursive + - name: Install doxygen run: | sudo apt-get update sudo apt-get install doxygen + - name: Build documentation and check for warnings - run: make doc + run: make clean doc build_Windows_Cygwin: From 43f2ea4a0c65f994e171b6a98ab186ffd7ab4954 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 09:29:36 -0500 Subject: [PATCH 07/17] github actions: re-organize yaml scripts - remove "main.yml" - move job "build_nix" into script "main_nix.yml" - move job "check_documentation" into script "check_doc.yml" - move job "build_Windows_Cygwin" into script "main_win.yml" --- .github/workflows/{main.yml => main_nix.yml} | 55 -------------------- 1 file changed, 55 deletions(-) rename .github/workflows/{main.yml => main_nix.yml} (54%) diff --git a/.github/workflows/main.yml b/.github/workflows/main_nix.yml similarity index 54% rename from .github/workflows/main.yml rename to .github/workflows/main_nix.yml index f539a8e1d..32b02059b 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main_nix.yml @@ -62,58 +62,3 @@ jobs: uses: codecov/codecov-action@v2 with: fail_ci_if_error: false # just report, don't fail checks - - - check_documentation: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository and submodules - uses: actions/checkout@v2 - with: - submodules: recursive - - - name: Install doxygen - run: | - sudo apt-get update - sudo apt-get install doxygen - - - name: Build documentation and check for warnings - run: make clean doc - - - build_Windows_Cygwin: - # see https://github.com/cygwin/cygwin-install-action - # based on https://github.com/resurrecting-open-source-projects/scrot - - runs-on: windows-latest - env: - CYGWIN_NOWINPATH: 1 # only have cygwin's executables on PATH - CHERE_INVOKING: 1 # prevent profile script to change directory - defaults: - run: - shell: C:\cygwin\bin\bash.exe --login -eo pipefail -o igncr {0} - - steps: - - run: git config --global core.autocrlf input - shell: bash - - - name: Checkout repository and submodules - uses: actions/checkout@v2 - with: - submodules: recursive - - - name: Install cygwin (windows) - uses: cygwin/cygwin-install-action@v1 - with: - packages: gcc-core gcc-g++ make - - - name: Print compiler versions as seen by make - run: make compiler_version - - # AddressSanitizer and LeakSanitizer not available on cygwin - - name: Run binary - run: make clean bin bint_run - - - name: Unit tests - run: make clean test test_run From a5b21e9db3fba062ff99725703067adfe1d86dfd Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Mon, 24 Jan 2022 09:36:14 -0500 Subject: [PATCH 08/17] Update README - update compiler version requirements for unit tests - update status badges (moving from travis and appveyor to github actions) --- README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0ded6f841..fc84b330c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ -| *nix | Windows | Release | DOI | License | Coverage | -| :---- | :---- | :---- | :---- | :---- | :---- | -[ ![Travis build status][1]][2] | [![Appveyor build status][3]][4] | [ ![github release][5]][6] | [ ![DOI][7]][8] | [![license][9]][10] | [![codecov status][11]][12] | +| *nix | Windows | Release | DOI | License | Coverage | Documentation | +| :---- | :---- | :---- | :---- | :---- | :---- | :---- | +[ ![gh nix build status][1]][2] | [![gh win build status][3]][2] | [ ![github release][5]][6] | [ ![DOI][7]][8] | [![license][9]][10] | [![codecov status][11]][12] | [![doc status][4]][2] | -[1]: https://travis-ci.org/DrylandEcology/SOILWAT2.svg?branch=master -[2]: https://travis-ci.org/DrylandEcology/SOILWAT2 -[3]: https://ci.appveyor.com/api/projects/status/noes9lralyjhen3t/branch/master?svg=true -[4]: https://ci.appveyor.com/project/DrylandEcologyGit/soilwat2/branch/master +[1]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/main_nix.yml/badge.svg?branch=master +[2]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows +[3]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/main_win.yml/badge.svg?branch=master +[4]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/check_doc.yml/badge.svg?branch=master + [5]: https://img.shields.io/github/release/DrylandEcology/SOILWAT2.svg [6]: https://github.com/DrylandEcology/SOILWAT2/releases [7]: https://zenodo.org/badge/9551524.svg @@ -15,6 +16,7 @@ [10]: https://www.gnu.org/licenses/gpl.html [11]: https://codecov.io/gh/DrylandEcology/SOILWAT2/branch/master/graph/badge.svg [12]: https://codecov.io/gh/DrylandEcology/SOILWAT2 + [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2 [rSOILWAT2]: https://github.com/DrylandEcology/rSOILWAT2 [STEPWAT2]: https://github.com/DrylandEcology/STEPWAT2 @@ -82,7 +84,7 @@ A detailed manual can be found ### Compilation * Requirements: - the `gcc` or `clang/llvm` toolchains - - `gcc >= v4.9` and `clang >= v3.3` for the `*_severe` test/debug targets + - `gcc >= v5` and `clang >= v5` for the `*_severe` test/debug targets - POSIX- or GNU-compliant `make` - On Windows OS: an installation of `cygwin` @@ -240,7 +242,7 @@ following output is implemented: __Continous integration checks__ Development/feature branches can only be merged into master if they pass -all checks on `appveyor` and `travis` continuous integration servers, i.e., +all checks on the continuous integration servers, i.e., run the following locally to prepare a pull-request or commit to be reviewed ```{.sh} make clean bin_debug_severe bint_run From 86d91ff65eb8ca59b7940c3712704da1d36ce0ea Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 09:43:50 -0500 Subject: [PATCH 09/17] github actions: create check_doc.yml - move job "check_documentation" into script "check_doc.yml" (previously in "main.yml") - install also doxygen-latex and graphviz dependencies --- .github/workflows/check_doc | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/workflows/check_doc diff --git a/.github/workflows/check_doc b/.github/workflows/check_doc new file mode 100644 index 000000000..27457d5b7 --- /dev/null +++ b/.github/workflows/check_doc @@ -0,0 +1,28 @@ +name: SOILWAT2 doc CI + +on: + push: + branches: + - master + pull_request: + branches: + - master + +jobs: + check_documentation: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository and submodules + uses: actions/checkout@v2 + with: + submodules: recursive + + - name: Install doxygen and dependencies + # SOILWAT2 documentation uses bibtex to build references + run: | + sudo apt-get update + sudo apt-get install doxygen doxygen-latex graphviz + + - name: Build documentation and check for warnings + run: make clean doc From f468bea387ba39ca2f05acff9c5ef58cb4d921ea Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 09:46:04 -0500 Subject: [PATCH 10/17] github actions: correctly name "check_doc.yml" --- .github/workflows/{check_doc => check_doc.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{check_doc => check_doc.yml} (100%) diff --git a/.github/workflows/check_doc b/.github/workflows/check_doc.yml similarity index 100% rename from .github/workflows/check_doc rename to .github/workflows/check_doc.yml From 9718a5a4ebb494e2b40ab164093be2725cd080ae Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 10:36:11 -0500 Subject: [PATCH 11/17] github actions: use shorter name for doc workflow - workflow names are used in badges on README -> long names display poorly --- .github/workflows/check_doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check_doc.yml b/.github/workflows/check_doc.yml index 27457d5b7..e2fb68762 100644 --- a/.github/workflows/check_doc.yml +++ b/.github/workflows/check_doc.yml @@ -1,4 +1,4 @@ -name: SOILWAT2 doc CI +name: docs on: push: From 3949a70f9c3ddef47e16fd892ade9392bb70e5e1 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 10:37:20 -0500 Subject: [PATCH 12/17] github actions: use shorter name for nix workflow - workflow names are used in badges on README -> long names display poorly --- .github/workflows/main_nix.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main_nix.yml b/.github/workflows/main_nix.yml index 32b02059b..6286332b2 100644 --- a/.github/workflows/main_nix.yml +++ b/.github/workflows/main_nix.yml @@ -1,4 +1,4 @@ -name: SOILWAT2 C/C++ CI +name: tests #TODO: run unit tests with different compiler versions of both gcc and clang From 59f03ef14217977a1fd9f25e5e44bd6bebba41f5 Mon Sep 17 00:00:00 2001 From: Daniel R Schlaepfer Date: Mon, 24 Jan 2022 10:38:05 -0500 Subject: [PATCH 13/17] github actions: use shorter name for win workflow - workflow names are used in badges on README -> long names display poorlygithub actions: use shorter name for doc workflow --- .github/workflows/main_win.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main_win.yml b/.github/workflows/main_win.yml index 21389984d..18f029d16 100644 --- a/.github/workflows/main_win.yml +++ b/.github/workflows/main_win.yml @@ -1,4 +1,4 @@ -name: SOILWAT2 cygwin CI +name: win-tests #TODO: run unit tests with different compiler versions of both gcc and clang From d214cb9254edaceed6f62856e8b5efe8d22c89b4 Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Mon, 24 Jan 2022 10:51:02 -0500 Subject: [PATCH 14/17] Update README: simplify badges --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fc84b330c..2b397a0dd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ -| *nix | Windows | Release | DOI | License | Coverage | Documentation | -| :---- | :---- | :---- | :---- | :---- | :---- | :---- | -[ ![gh nix build status][1]][2] | [![gh win build status][3]][2] | [ ![github release][5]][6] | [ ![DOI][7]][8] | [![license][9]][10] | [![codecov status][11]][12] | [![doc status][4]][2] | + +[![gh nix build status][1]][2] +[![gh win build status][3]][2] +[![github release][5]][6] +[![DOI][7]][8] +[![license][9]][10] +[![codecov status][11]][12] +[![doc status][4]][2] + [1]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/main_nix.yml/badge.svg?branch=master From 606de7252eb01825a6ccfa8b7b62392e4b843c13 Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Mon, 24 Jan 2022 10:52:36 -0500 Subject: [PATCH 15/17] Fix doxygen documentation "empty return type" - fix doxygen "warning: documented empty return type ..." for functions that return "void": `lyrSoil_to_lyrTemp()`, `pot_soil_evap_bs()`, `write_headers_to_csv()` --- SW_Flow_lib.c | 37 +++++++++++++++++-------------------- SW_Output_outtext.c | 1 - 2 files changed, 17 insertions(+), 21 deletions(-) diff --git a/SW_Flow_lib.c b/SW_Flow_lib.c index b9ae67d98..2391d8335 100644 --- a/SW_Flow_lib.c +++ b/SW_Flow_lib.c @@ -509,18 +509,16 @@ void pot_soil_evap(double *bserate, unsigned int nelyrs, double ecoeff[], double Based on equations from Parton 1978. @cite Parton1978 -@param *bserate Bare soil evaporation loss rate (cm/day). -@param nelyrs Number of layers to consider in evaporation. -@param ecoeff Array of evaporation coefficients. -@param petday Potential evapotranspiration rate (cm/day). -@param shift Displacement of the inflection point in order to shift the function up, down, left, or right. -@param shape Slope of the line at the inflection point. -@param inflec Y-value of the inflection point. -@param range Max y-value - min y-value at the limits. -@param width Width of each layer (cm). -@param swc Soilwater content in each layer before drainage (m3 H2O). - -@return *bserate Updated bare soil evaporation loss rate (cm/day). +@param[in,out] *bserate Bare soil evaporation loss rate (cm/day). +@param[in] nelyrs Number of layers to consider in evaporation. +@param[in] ecoeff Array of evaporation coefficients. +@param[in] petday Potential evapotranspiration rate (cm/day). +@param[in] shift Displacement of the inflection point in order to shift the function up, down, left, or right. +@param[in] shape Slope of the line at the inflection point. +@param[in] inflec Y-value of the inflection point. +@param[in] range Max y-value - min y-value at the limits. +@param[in] width Width of each layer (cm). +@param[in] swc Soilwater content in each layer before drainage (m3 H2O). */ @@ -1096,15 +1094,14 @@ void lyrSoil_to_lyrTemp_temperature(unsigned int nlyrSoil, double depth_Soil[], @brief Initialize soil temperature layer values by transfering soil layer values to soil temperature layer values. -@param cor Two dimensional array containing soil temperature data. -@param nlyrSoil Number of soil layers. -@param width_Soil Width of the soil layers. -@param var Soil layer values to be interpolated. -@param nlyrTemp Number of soil temperature layers. -@param width_Temp Width of the soil temperature layers. -@param res Values interpolated to soil temperature depths. +@param[in] cor Two dimensional array containing soil temperature data. +@param[in] nlyrSoil Number of soil layers. +@param[in] width_Soil Width of the soil layers. +@param[in] var Soil layer values to be interpolated. +@param[in] nlyrTemp Number of soil temperature layers. +@param[in] width_Temp Width of the soil temperature layers. +@param[in,out] res Values interpolated to soil temperature depths. -@return res is updated and reflects new values. */ void lyrSoil_to_lyrTemp(double cor[MAX_ST_RGR][MAX_LAYERS + 1], unsigned int nlyrSoil, diff --git a/SW_Output_outtext.c b/SW_Output_outtext.c index d5a894b89..83e6d9411 100644 --- a/SW_Output_outtext.c +++ b/SW_Output_outtext.c @@ -376,7 +376,6 @@ void get_outstrleader(OutPeriod pd, char *str) { \param does_agg Indicate whether output is aggregated (`-o` option) or for each SOILWAT2 run (`-i` option) - \return void. */ void write_headers_to_csv(OutPeriod pd, FILE *fp_reg, FILE *fp_soil, Bool does_agg) { char str_time[20]; From b562710ec27ad983d361b4ddb39bf2842d215b64 Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Mon, 24 Jan 2022 12:15:25 -0500 Subject: [PATCH 16/17] Update documentation - some doxygen hyperlinks no longer worked correctly -> use mostly markdown-style links (except for creating subpages) - however, html tags don't work for doxygen documentation (as of v1.9.3) (see issue #299) --- README.md | 9 ++++++-- ...user guide.md => A_SOILWAT2_user_guide.md} | 22 +++++++++++++------ ...{SOILWAT2 Inputs.md => SOILWAT2_Inputs.md} | 11 +++++++--- ...OILWAT2 Outputs.md => SOILWAT2_Outputs.md} | 13 +++++++---- 4 files changed, 39 insertions(+), 16 deletions(-) rename doc/additional_pages/{A SOILWAT2 user guide.md => A_SOILWAT2_user_guide.md} (86%) rename doc/additional_pages/{SOILWAT2 Inputs.md => SOILWAT2_Inputs.md} (90%) rename doc/additional_pages/{SOILWAT2 Outputs.md => SOILWAT2_Outputs.md} (82%) diff --git a/README.md b/README.md index 2b397a0dd..7afef4ea4 100644 --- a/README.md +++ b/README.md @@ -83,8 +83,13 @@ Some recent references ## How to get started -A detailed manual can be found -[here](`doc/additional_pages/A SOILWAT2 user guide.md`) or here \ref page_manual. +SOILWAT2 comes with a +[detailed manual](doc/additional_pages/A_SOILWAT2_user_guide.md) +and short overviews of +[inputs](doc/additional_pages/SOILWAT2_Inputs.md) +and [outputs](doc/additional_pages/SOILWAT2_Outputs.md). +A full code documentation may be built, see [here](#get_documentation). + ### Compilation diff --git a/doc/additional_pages/A SOILWAT2 user guide.md b/doc/additional_pages/A_SOILWAT2_user_guide.md similarity index 86% rename from doc/additional_pages/A SOILWAT2 user guide.md rename to doc/additional_pages/A_SOILWAT2_user_guide.md index 022490854..0f54579b5 100644 --- a/doc/additional_pages/A SOILWAT2 user guide.md +++ b/doc/additional_pages/A_SOILWAT2_user_guide.md @@ -1,5 +1,4 @@ -\page page_manual A SOILWAT2 user guide - +# A SOILWAT2 user guide [clang/llvm]: https://clang.llvm.org [cygwin]: https://www.cygwin.com @@ -14,6 +13,10 @@ [xcode]: https://developer.apple.com/xcode +Note: this document is best viewed as part of the doxygen-built documentation +(there may be text artifacts if viewed as standalone-markdown). + + The `SOILWAT2` program must be downloaded as source code and compiled from the command line. The program is written in `C` and has no graphical user interface. If you are more familiar with `R`, then you may prefer to use our R package @@ -35,7 +38,7 @@ on your side. ### Minimal requirements - on any platform: - the [gcc][] or [clang/llvm][] toolchains; - ideally, `gcc >= v4.9` or `clang >= v3.3` + ideally, `gcc >= v4.9` or `clang >= v3.3` (at least `v5.0` for testing) - POSIX- [make](https://pubs.opengroup.org/onlinepubs/9699919799/) or GNU-compliant [make](https://www.gnu.org/software/make/) - [git][] to download the code @@ -107,13 +110,16 @@ on your side. ### Documentation - * Generate help pages (locally) and open them in your browser + * Code documentation ```{.sh} cd SOILWAT2/ make doc make doc_open ``` + * Documentation of user inputs and outputs + * \subpage doc/additional_pages/SOILWAT2_Inputs.md "SOILWAT2 Inputs" + * \subpage doc/additional_pages/SOILWAT2_Outputs.md "SOILWAT2 Outputs"
@@ -134,16 +140,18 @@ on your side. ``` * The inputs comprise the master file `files.in` and the content of the - `Input/` folder. They are explained in detail \subpage page_inputs "here". + `Input/` folder. They are explained in detail + [here](doc/additional_pages/SOILWAT2_Inputs.md). * The outputs are written to `Output/` including a logfile that contains warnings and errors. The output files are in `.csv` format and can be opened by a spreadsheet program (e.g., `LibreOffice` or `Excel`) or imported into `R` (e.g., `data <- read.csv("testing/Output/sw2_yearly.csv")`). - Outputs are explained in detail \subpage page_outputs "here". + Outputs are explained in detail + [here](doc/additional_pages/SOILWAT2_Inputs.md).
-Go back to the \ref index "main page". +Go back to the [main page](README.md). diff --git a/doc/additional_pages/SOILWAT2 Inputs.md b/doc/additional_pages/SOILWAT2_Inputs.md similarity index 90% rename from doc/additional_pages/SOILWAT2 Inputs.md rename to doc/additional_pages/SOILWAT2_Inputs.md index 6905446bd..a166f5d9c 100644 --- a/doc/additional_pages/SOILWAT2 Inputs.md +++ b/doc/additional_pages/SOILWAT2_Inputs.md @@ -1,7 +1,11 @@ -\page page_inputs SOILWAT2 Inputs +# SOILWAT2 Inputs [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2 +Note: this document is best viewed as part of the doxygen-built documentation +(there may be text artifacts if viewed as standalone-markdown). + + ### Example * The source code contains a complete example simulation project in `testing/` * Copy the executable to the testing path, modify inputs as desired, @@ -22,7 +26,7 @@ \ref explain_inputs "below". * The outputs are written to `Output/` including a logfile that contains warnings and errors. Outputs are explained in detail - \ref page_outputs "here". + [here](doc/additional_pages/SOILWAT2_Outputs.md).
@@ -131,4 +135,5 @@ Go back to the \ref explain_inputs "list of input files"
-Go back to the \ref index "main page" or the \ref page_manual "user guide". +Go back to the [main page](README.md) or +[user guide](doc/additional_pages/A_SOILWAT2_user_guide.md). diff --git a/doc/additional_pages/SOILWAT2 Outputs.md b/doc/additional_pages/SOILWAT2_Outputs.md similarity index 82% rename from doc/additional_pages/SOILWAT2 Outputs.md rename to doc/additional_pages/SOILWAT2_Outputs.md index d54e0699d..77b38be54 100644 --- a/doc/additional_pages/SOILWAT2 Outputs.md +++ b/doc/additional_pages/SOILWAT2_Outputs.md @@ -1,7 +1,11 @@ -\page page_outputs SOILWAT2 Outputs +# SOILWAT2 Outputs [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2 +Note: this document is best viewed as part of the doxygen-built documentation +(there may be text artifacts if viewed as standalone-markdown). + + ### Example * The source code contains a complete example simulation project in `testing/` * Copy the executable to the testing path, modify inputs as desired, @@ -18,8 +22,8 @@ ``` * The inputs comprise the master file `files.in` and the content of the - `Input/` folder. They are explained in detail on the page - \ref page_inputs. + `Input/` folder. They are explained in detail + [here](doc/additional_pages/SOILWAT2_Inputs.md). * The user can turn on/off different types of outputs via the input file \ref outsetupin. * The outputs are written to the folder `Output/` including a @@ -56,4 +60,5 @@ The names of the output files are user inputs in the file \ref filesin.
-Go back to the \ref index "main page" or the \ref page_manual "user guide". +Go back to the [main page](README.md) or +[user guide](doc/additional_pages/A_SOILWAT2_user_guide.md). From 3ecbdc9d0ab7bd7e668dbcdbe8725331591d1d1d Mon Sep 17 00:00:00 2001 From: Daniel Schlaepfer Date: Mon, 24 Jan 2022 12:21:33 -0500 Subject: [PATCH 17/17] Remove obsolete doxygen exception - close issue #267 (Remove from doc/doxygen_exceptions.txt: "Unexpected html tag ...") - doxygen issue resolved with v1.8.16 (github actions installs v1.8.17 on ubuntu-release; and I get v1.9.3) --- doc/doxygen_exceptions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/doxygen_exceptions.txt b/doc/doxygen_exceptions.txt index ba9333dbf..8b1378917 100755 --- a/doc/doxygen_exceptions.txt +++ b/doc/doxygen_exceptions.txt @@ -1 +1 @@ -warning: Unexpected html tag found within context +