Standardize doc-strings

.github/workflows/gh-pages.yml

@@ -1,8 +1,7 @@
 name: docs
 on:
   push:
-    branches:
-      - main
+  pull_request:
 
 jobs:
   build:
@@ -17,12 +16,16 @@ jobs:
       - name: Dependencies
         run: |
           if [ -f pyproject.toml ]; then pip install ".[docs]"; fi
+      - name: Clear notebooks and create conf.py file
+        run: |
+          jupyter-book config sphinx docs/
+          jupyter nbconvert --ClearOutputPreprocessor.enabled=True --ClearMetadataPreprocessor.enabled=True --clear-output --inplace $(find . -type f -name '*.ipynb')
       - name: Build Sphinx Documentation
         run: |
           sphinx-build docs _build/html -b html
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
-        if: job.status == 'success'
+        if: github.ref == 'refs/heads/main' && job.status == 'success'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./_build/html

.gitignore

@@ -132,3 +132,8 @@ dmypy.json
 _build/
 docs/api/
 src/GOSTurban/_version.py
+docs/notebooks/
+
+# ignore the generated sphinx conf.py file
+# we generate it during the doc build using jupyter-book from _conf.py
+docs/conf.py

.pre-commit-config.yaml

@@ -29,6 +29,8 @@ repos:
       - id: codespell
         name: codespell
         description: Checks for common misspellings in text files
+        additional_dependencies:
+          - tomli
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.2.2
     hooks:

README.md

@@ -36,13 +36,15 @@ pip install GOSTurban
     pip install .
     ```
 
-    Install the package **in editable** mode with dependencies:
+### Developer Installation
 
-    ```shell
-    pip install -e .
-    ```
+Install the package **in editable** mode with all of the dependencies needed to run the tests and build the documentation locally:
+
+ ```shell
+ pip install -e .[dev]
+ ```
 
-    The `-e` flag stands for "editable," meaning changes to the source code will immediately affect the installed package.
+The `-e` flag stands for "editable," meaning changes to the source code will immediately affect the installed package.
 
 ## License
 

docs/_config.yml

@@ -8,7 +8,11 @@ logo: images/logo.png
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
 execute:
-  execute_notebooks: off
+  execute_notebooks: force
+  allow_errors: true
+
+# only build files in toc
+only_build_toc: true
 
 # Add a bibtex file so that we can create citations
 bibtex_bibfiles:
@@ -25,3 +29,11 @@ repository:
 html:
   use_issues_button: false
   use_repository_button: true
+
+# specify sphinx extensions
+sphinx:
+  extra_extensions:
+    - sphinx.ext.napoleon
+    - sphinxcontrib.apidoc
+  config:
+    apidoc_module_dir: ../src

docs/_toc.yml

@@ -15,4 +15,39 @@ parts:
     chapters:
       - file: notebooks/Tutorials/UrbanAreas_tutorials.ipynb
       - file: notebooks/Tutorials/LEI_Example.ipynb
-
+  # - caption: Implementations
+  #   chapters:
+  #     - file: notebooks/Implementations/JUP_SURGP_GLO_B_D__LEI_Evaluation.ipynb
+  #     - file: notebooks/Implementations/URB_DECAT_B_ExploringGHSSMODcode.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_B_A_Ka_ExtractDataUrban.ipynb
+  #     - file: notebooks/Implementations/WSF_DECAT_B_ExploringIDCerrors.ipynb
+  # - caption: KAZ_SCADR_UrbanizationReview
+  #   chapters:
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/ECA_Urban_Extents.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/Urban_metrics_Combine_All.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/Urban_metrics_Shape.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/Urban_metrics_Structure.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/KAZ_Urbanization_Review.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/Urban_metrics_Fullness.ipynb
+  #     - file: notebooks/Implementations/KAZ_SCADR_UrbanizationReview/Urban_metrics_Sprawl.ipynb
+  # - caption: POV_EEAPV_COG_urban_assessment
+  #   chapters:
+  #     - file: notebooks/Implementations/POV_EEAPV_COG_urban_assessment/Summarize_Urban.ipynb
+  # - caption: Slum_Mapping
+  #   chapters:
+  #     - file: notebooks/Implementations/Slum_Mapping/Imagery_Search.ipynb
+  # - caption: URB_SCAUR_UKR_B_I_urbanizationReview
+  #   chapters:
+  #     - file: notebooks/Implementations/URB_SCAUR_UKR_B_I_urbanizationReview/URB_SCAUR_UKR_B_I_urbanizationReview.ipynb
+  # - caption: URB_SEAU1_NovelUrbanization
+  #   chapters:
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/Create_Mosaick_Datasets.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/GHSL_Standardize_To_Country.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/MAP_Urbanization.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/NGA_specific_results.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/URB_SEAU1_B_A_Ka_NovelUrbanizaton.ipynb
+  #     - file: notebooks/Implementations/URB_SEAU1_NovelUrbanization/WBGAPI_Extract_urbanization_GDP.ipynb
+  # - caption: URB_SURDR_ZAF_Energy_Transition
+  #   chapters:
+  #     - file: notebooks/Implementations/URB_SURDR_ZAF_Energy_Transition/Data Preparation.ipynb
+  #     - file: notebooks/Implementations/URB_SURDR_ZAF_Energy_Transition/Zonal_statistics.ipynb

notebooks/Implementations/JUP_SURGP_GLO_B_D__LEI_Evaluation.ipynb

@@ -12,24 +12,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {},
-   "outputs": [
-    {
-     "ename": "ModuleNotFoundError",
-     "evalue": "No module named 'src.LEI'",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
-      "\u001b[0;32m/tmp/ipykernel_81457/3673388608.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m     14\u001b[0m \u001b[0;31m#Import GOST urban functions\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     15\u001b[0m \u001b[0msys\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mpath\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mappend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"../../\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 16\u001b[0;31m \u001b[0;32mfrom\u001b[0m \u001b[0msrc\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mLEI\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0;34m*\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'src.LEI'"
-     ]
-    }
-   ],
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "import os\n",
-    "import sys\n",
     "\n",
     "import rasterio\n",
     "import rasterio.features\n",
@@ -41,16 +28,13 @@
     "from rasterio.plot import show\n",
     "\n",
     "# Import GOST urban functions\n",
-    "sys.path.append(\"../../\")\n",
-    "from src.LEI import *"
+    "from GOSTurban.LEI import calculate_LEI, summarize_LEI"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "scrolled": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "LEI_folder = \"/home/wb411133/data/Projects/LEI\"\n",
@@ -72,7 +56,7 @@
     "                    os.stat(os.path.join(root, \"GHSL.tif\")).st_size,\n",
     "                )\n",
     "            )\n",
-    "    except:\n",
+    "    except Exception:\n",
     "        pass"
    ]
   },
@@ -81,7 +65,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Vizualize raster data - GHSL"
+    "# Visualize raster data - GHSL"
    ]
   },
   {
@@ -118,7 +102,7 @@
    "source": [
     "# write out raster to file\n",
     "outProperties = inRaster.profile\n",
-    "outRaster = outRaster.astype(\"int32\")\n",
+    "outRaster = inRaster.astype(\"int32\")\n",
     "outProperties[\"dtype\"] = \"int32\"\n",
     "with rasterio.open(inputGHSL.replace(\".tif\", \"_LEI.tif\"), \"w\", **outProperties) as out:\n",
     "    out.write(outRaster)"
@@ -135,9 +119,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "scrolled": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "for ghsl_file in GHSL_files:\n",
@@ -412,22 +394,8 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "Python (geog)",
-   "language": "python",
-   "name": "geog"
-  },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "name": "python"
   }
  },
  "nbformat": 4,