Update Documentation (#21)

* update docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * remove docs/notebooks * Revert "[pre-commit.ci] auto fixes from pre-commit.com hooks" This reverts commit 2eb4db3. * Revert "remove docs/notebooks" This reverts commit 9f660ff. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * modify toc to only include notebook tutorials, clear notebook outputs * fix deps, imports, and ci * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * generate conf.py as part of docs build workflow * have workflow clean notebooks * add extensions, options etc to _config.yml * cleaned notebooks * remove non-functional exclusions * build docs on prs, only deploy on main * require nbconvert for docs * add nbstrip git-hook * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
worldbank · Jun 17, 2024 · a1c5366 · a1c5366
1 parent 6050ebb
commit a1c5366
Show file tree

Hide file tree

Showing 40 changed files with 1,733 additions and 235,597 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.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

diff --git a/.gitignore b/.gitignore
@@ -132,3 +132,11 @@ 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
+
+# ignore implementations output
+notebooks/Implementations/output/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -37,3 +37,7 @@ repos:
         args: [--fix]
       - id: ruff-format
         types_or: [python, pyi, jupyter]
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.7.1
+    hooks:
+      - id: nbstripout
diff --git a/README.md b/README.md
@@ -35,14 +35,15 @@ pip install GOSTurban
     ```shell
     pip install .
     ```
+### Developer Installation
 
-    Install the package **in editable** mode with dependencies:
+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 .
-    ```
+ ```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
 

diff --git a/docs/_config.yml b/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
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -15,3 +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
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/notebooks/Implementations/JUP_SURGP_GLO_B_D__LEI_Evaluation.ipynb b/notebooks/Implementations/JUP_SURGP_GLO_B_D__LEI_Evaluation.ipynb
@@ -12,21 +12,9 @@
   },
   {
    "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",
@@ -48,9 +36,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "scrolled": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "LEI_folder = \"/home/wb411133/data/Projects/LEI\"\n",
@@ -135,9 +121,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "scrolled": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "for ghsl_file in GHSL_files:\n",
@@ -412,22 +396,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,