diff --git a/.github/workflows/check_doc.yml b/.github/workflows/check_doc.yml new file mode 100644 index 000000000..e2fb68762 --- /dev/null +++ b/.github/workflows/check_doc.yml @@ -0,0 +1,28 @@ +name: docs + +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 diff --git a/.github/workflows/main.yml b/.github/workflows/main_nix.yml similarity index 51% rename from .github/workflows/main.yml rename to .github/workflows/main_nix.yml index f404b874c..6286332b2 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main_nix.yml @@ -1,7 +1,6 @@ -name: SOILWAT2 C/C++ CI +name: tests -#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 @@ -25,10 +24,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 @@ -36,63 +35,30 @@ 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 - - name: Upload coverage to Codecov (ubuntu) - if: ${{ runner.os == 'Linux' && success() }} - 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 - CHERE_INVOKING: 1 # prevent profile script to change directory - defaults: - run: - shell: C:\cygwin\bin\bash.exe --login -eo pipefail -o igncr {0} + check_code_coverage: + runs-on: ubuntu-latest + 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 make - - - name: Print compiler versions as seen by make - run: make compiler_version - - - name: Run binary - run: | - make clean bin bint_run - make clean bin_debug_severe bint_run - - name: Unit tests - run: make clean test test_run - - - name: Severe unit tests (without sanitizers) - run: make clean test_severe test_run + - name: Generate coverage report + run: make clean cov cov_run + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v2 + with: + fail_ci_if_error: false # just report, don't fail checks 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 diff --git a/README.md b/README.md index 0ded6f841..7afef4ea4 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,19 @@ -| *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] | + +[![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 +[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 - -[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 [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 +22,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 @@ -75,14 +83,19 @@ 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 * 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 +253,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 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_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; 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]; 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). 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 +