354 from pdoc to mkdocs to sphinx (#846)

* updated docs to sphinx

* updated workflow file

* updated pyproject.toml docs dependencies to sphinx

.github/workflows/mkdocs-gh-deploy.yml → .github/workflows/sphinx-docs.yml

@@ -1,33 +1,34 @@
-name: mkdocs-gh-deploy
+name: sphinx-docs
+
 on:
   push:
-    branches:
-      - main
+    branches: ["main"]
+
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: windows-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-      - uses: actions/cache@v2
-        with:
-          key: ${{ github.ref }}
-          path: .cache
+      - uses: actions/setup-python@v3
+      - name: install pandoc
+        # pip install is not seen somehow, so via choco
+        run: |
+          choco install pandoc
       - name: Install dependencies
         run: |
-            python -m pip install --upgrade pip
-            python -m pip install -e .[docs]
-      - name: copying files and mkdocs build
+          python -m pip install --upgrade pip
+          python -m pip install -e .[docs]
+      - name: Sphinx build
         run: |
-            cp README.md docs
-            mkdocs build
+          sphinx-build docs docs/_build
       - uses: actions/upload-pages-artifact@v1
         with:
-          path: site/
+          path: docs/_build/
 
   # Deploy the artifact to GitHub pages.
   # This is a separate job so that only actions/deploy-pages has the necessary permissions.
@@ -42,4 +43,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v1

dfm_tools/__init__.py

@@ -1,5 +1,5 @@
 """
-.. include:: ../README.md
+Pre- and postprocessing D-FlowFM model input and output files
 """
 
 __author__ = """Jelmer Veenstra"""

dfm_tools/coastlines.py

@@ -36,7 +36,7 @@ def get_coastlines_gdb(res:str='h', bbox:tuple = (-180, -90, 180, 90), min_area:
     min_area : float, optional
         in km2, min_area>0 speeds up process. The default is 0.
     crs : str, optional
-        
+        coordinate reference system
     include_fields : list, optional
         which shapefile fields to include, None gives all. The default is ['area'].
 
@@ -97,6 +97,7 @@ def get_borders_gdb(res:str='h', bbox:tuple = (-180, -90, 180, 90), crs:str = No
     bbox : tuple, optional
         (minx, miny, maxx, maxy), also includes shapes that are partly in the bbox. The default is (-180, -90, 180, 90).
     crs : str, optional
+        coordinate reference system
     
     Returns
     -------

dfm_tools/get_nc.py

@@ -517,7 +517,7 @@ def plot_ztdata(data_xr_sel, varname, ax=None, only_contour=False, **kwargs):
         the figure axis. The default is None.
     only_contour : bool, optional
         Wheter to plot contour lines of the dataset. The default is False.
-    **kwargs : TYPE
+    kwargs : TYPE
         properties to give on to the pcolormesh function.
     
     Raises

dfm_tools/interpolate_grid2bnd.py

@@ -42,21 +42,22 @@ def get_conversion_dict(ncvarname_updates={}):
     data_xr = data_xr.rename({ncvarname:quantity})
     
     for CMCC:
-    conversion_dict = { # conversion is phyc in mol/m3 to newvar in g/m3
-                       'tracerbndOXY'        : {'ncvarname': 'o2',          'unit': 'g/m3', 'conversion': 32.0 },
-                       'tracerbndNO3'        : {'ncvarname': 'no3',         'unit': 'g/m3', 'conversion': 14.0 },
-                       'tracerbndPO4'        : {'ncvarname': 'po4',         'unit': 'g/m3', 'conversion': 30.97 },
-                       'tracerbndSi'         : {'ncvarname': 'si',          'unit': 'g/m3', 'conversion': 28.08},
-                       'tracerbndPON1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 14.0}, # Caution: this empirical relation might not be applicable to your use case
-                       'tracerbndPOP1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 30.97}, # Caution: this empirical relation might not be applicable to your use case
-                       'tracerbndPOC1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 14.0 * (106 / 16)}, # Caution: this empirical relation might not be applicable to your use case
-                       'salinitybnd'         : {'ncvarname': 'sos'},         #'1e-3'
-                       'temperaturebnd'      : {'ncvarname': 'tos'},         #'degC'
-                       'ux'                  : {'ncvarname': 'uo'},          #'m/s'
-                       'uy'                  : {'ncvarname': 'vo'},          #'m/s'
-                       'waterlevelbnd'       : {'ncvarname': 'zos'},         #'m' #steric
-                       'tide'                : {'ncvarname': ''},            #'m' #tide (dummy entry)
-                       }
+    conversion_dict = {
+    # conversion is phyc in mol/m3 to newvar in g/m3
+    'tracerbndOXY'        : {'ncvarname': 'o2',          'unit': 'g/m3', 'conversion': 32.0 },
+    'tracerbndNO3'        : {'ncvarname': 'no3',         'unit': 'g/m3', 'conversion': 14.0 },
+    'tracerbndPO4'        : {'ncvarname': 'po4',         'unit': 'g/m3', 'conversion': 30.97 },
+    'tracerbndSi'         : {'ncvarname': 'si',          'unit': 'g/m3', 'conversion': 28.08},
+    'tracerbndPON1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 14.0}, # Caution: this empirical relation might not be applicable to your use case
+    'tracerbndPOP1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 30.97}, # Caution: this empirical relation might not be applicable to your use case
+    'tracerbndPOC1'       : {'ncvarname': 'phyc',        'unit': 'g/m3', 'conversion': 14.0 * (106 / 16)}, # Caution: this empirical relation might not be applicable to your use case
+    'salinitybnd'         : {'ncvarname': 'sos'},         #'1e-3'
+    'temperaturebnd'      : {'ncvarname': 'tos'},         #'degC'
+    'ux'                  : {'ncvarname': 'uo'},          #'m/s'
+    'uy'                  : {'ncvarname': 'vo'},          #'m/s'
+    'waterlevelbnd'       : {'ncvarname': 'zos'},         #'m' #steric
+    'tide'                : {'ncvarname': ''},            #'m' #tide (dummy entry)
+    }
     
     
     The below clarification about the CMEMS conversion factors in this function is by Jos van Gils.
@@ -447,7 +448,7 @@ def interp_regularnc_to_plipointsDataset(data_xr_reg, gdf_points, load=True):
 
 def interp_uds_to_plipoints(uds:xu.UgridDataset, gdf:geopandas.GeoDataFrame, nPoints:int=None) -> xr.Dataset:
     """
-    To interpolate an unstructured dataset (like a *_map.nc file) read with xugrid to plipoint locations
+    To interpolate an unstructured dataset (like a _map.nc file) read with xugrid to plipoint locations
     
     Parameters
     ----------

dfm_tools/xugrid_helpers.py

@@ -192,19 +192,20 @@ def open_partitioned_dataset(file_nc, decode_fillvals=False, remove_edges=True,
     ds_merged_xu : TYPE
         DESCRIPTION.
     
-    file_nc = 'p:\\1204257-dcsmzuno\\2006-2012\\3D-DCSM-FM\\A18b_ntsu1\\DFM_OUTPUT_DCSM-FM_0_5nm\\DCSM-FM_0_5nm_0*_map.nc' #3D DCSM
-    file_nc = 'p:\\archivedprojects\\11206813-006-kpp2021_rmm-2d\\C_Work\\31_RMM_FMmodel\\computations\\model_setup\\run_207\\results\\RMM_dflowfm_0*_map.nc' #RMM 2D
-    file_nc = 'p:\\1230882-emodnet_hrsm\\GTSMv5.0\\runs\\reference_GTSMv4.1_wiCA_2.20.06_mapformat4\\output\\gtsm_model_0*_map.nc' #GTSM 2D
-    file_nc = 'p:\\11208053-005-kpp2022-rmm3d\\C_Work\\01_saltiMarlein\\RMM_2019_computations_02\\computations\\theo_03\\DFM_OUTPUT_RMM_dflowfm_2019\\RMM_dflowfm_2019_0*_map.nc' #RMM 3D
-    file_nc = 'p:\\archivedprojects\\11203379-005-mwra-updated-bem\\03_model\\02_final\\A72_ntsu0_kzlb2\\DFM_OUTPUT_MB_02\\MB_02_0*_map.nc'
-    Timings (xu.open_dataset/xu.merge_partitions):
-        - DCSM 3D 20 partitions  367 timesteps: 231.5/ 4.5 sec (decode_times=False: 229.0 sec)
-        - RMM  2D  8 partitions  421 timesteps:  55.4/ 4.4 sec (decode_times=False:  56.6 sec)
-        - GTSM 2D  8 partitions  746 timesteps:  71.8/30.0 sec (decode_times=False: 204.8 sec)
-        - RMM  3D 40 partitions  146 timesteps: 168.8/ 6.3 sec (decode_times=False: 158.4 sec)
-        - MWRA 3D 20 partitions 2551 timesteps:  74.4/ 3.4 sec (decode_times=False:  79.0 sec)
-    
     """
+    # TODO: timings
+    # file_nc = 'p:\\1204257-dcsmzuno\\2006-2012\\3D-DCSM-FM\\A18b_ntsu1\\DFM_OUTPUT_DCSM-FM_0_5nm\\DCSM-FM_0_5nm_0*_map.nc' #3D DCSM
+    # file_nc = 'p:\\archivedprojects\\11206813-006-kpp2021_rmm-2d\\C_Work\\31_RMM_FMmodel\\computations\\model_setup\\run_207\\results\\RMM_dflowfm_0*_map.nc' #RMM 2D
+    # file_nc = 'p:\\1230882-emodnet_hrsm\\GTSMv5.0\\runs\\reference_GTSMv4.1_wiCA_2.20.06_mapformat4\\output\\gtsm_model_0*_map.nc' #GTSM 2D
+    # file_nc = 'p:\\11208053-005-kpp2022-rmm3d\\C_Work\\01_saltiMarlein\\RMM_2019_computations_02\\computations\\theo_03\\DFM_OUTPUT_RMM_dflowfm_2019\\RMM_dflowfm_2019_0*_map.nc' #RMM 3D
+    # file_nc = 'p:\\archivedprojects\\11203379-005-mwra-updated-bem\\03_model\\02_final\\A72_ntsu0_kzlb2\\DFM_OUTPUT_MB_02\\MB_02_0*_map.nc'
+    # Timings (xu.open_dataset/xu.merge_partitions):
+    # - DCSM 3D 20 partitions  367 timesteps: 231.5/ 4.5 sec (decode_times=False: 229.0 sec)
+    # - RMM  2D  8 partitions  421 timesteps:  55.4/ 4.4 sec (decode_times=False:  56.6 sec)
+    # - GTSM 2D  8 partitions  746 timesteps:  71.8/30.0 sec (decode_times=False: 204.8 sec)
+    # - RMM  3D 40 partitions  146 timesteps: 168.8/ 6.3 sec (decode_times=False: 158.4 sec)
+    # - MWRA 3D 20 partitions 2551 timesteps:  74.4/ 3.4 sec (decode_times=False:  79.0 sec)
+
     #TODO: add support for multiple grids via keyword? https://github.com/Deltares/dfm_tools/issues/497
     #TODO: speed up open_dataset https://github.com/Deltares/dfm_tools/issues/225 (also remove_ghost)
 

docs/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Information for developers
+# Contributing
 
 ## Checkout dfm_tools git repository
 
@@ -12,7 +12,7 @@
 
 ## Setup local developer environment
 
-- python 3.11 is recommended, python>=3.9 is required ([more info](https://github.com/Deltares/dfm_tools/issues/267)), python 3.13 not yet supported ([more info](https://github.com/Deltares/dfm_tools/issues/559))
+- python 3.11 is recommended, [python>=3.9 is required](https://github.com/Deltares/dfm_tools/issues/267), [python 3.13 not yet supported](https://github.com/Deltares/dfm_tools/issues/559)
 - download and install Anaconda from [anaconda.com](https://www.anaconda.com)
 - open anaconda prompt and navigate to dfm_tools checkout folder, e.g. ``C:\DATA\dfm_tools``
 - ``conda create --name dfm_tools_env python=3.11 git spyder -c conda-forge -y`` (``git`` and ``spyder`` are optional)
@@ -37,23 +37,22 @@
 - request a review on the pull request
 - after review, squash+merge the branch into main
 
-## Running the testbank (also partly runs on github automatically)
+## Running the testbank
 
 - open anaconda prompt in local dfm_tools folder (e.g. ``C:\DATA\dfm_tools``)
 - ``conda activate dfm_tools_env``
 - ``pytest`` (runs all tests)
 - ``pytest -m "not acceptance"``
 - ``pytest -m acceptance`` (runs the acceptance tests, which are the scripts in [the examples folder](https://github.com/Deltares/dfm_tools/tree/main/tests/examples))
 - ``pytest -m "not requireslocaldata"`` (this is what runs on github)
+- this workflow automatically runs via Github Actions upon push and pullrequest to main
 
-## Generate documentation with mkdocs (automatically runs via Github Actions upon push to main)
+## Generate documentation with sphinx
 
 - open anaconda prompt in local dfm_tools folder (e.g. ``C:\DATA\dfm_tools``)
 - ``conda activate dfm_tools_env``
-```
-cp README.md docs
-mkdocs build
-```
+- ``sphinx-build docs docs/_build``
+- this workflow automatically runs via Github Actions upon push to main
 
 ## Increase the dfm_tools version number
 

docs/_static/theme-deltares.css

@@ -0,0 +1,4 @@
+/* enlarge deltares & github icon size; only works with local/url svg files; not with fa icons */
+img.icon-link-image {
+    height: 2.5em !important;
+}