reorg for docs

.github/workflows/gh-pages.yml

@@ -0,0 +1,32 @@
+name: docs
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+          cache: "pip"
+      - 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: github.ref == 'refs/heads/main' && job.status == 'success'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_build/html
+          enable_jekyll: false

docs/_config.yml

@@ -1,7 +1,7 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
 
-title: GOST Urbanization
+title: GOSTnets
 author: Benjamin P. Stewart
 logo: images/logo.png
 
@@ -20,7 +20,7 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/worldbank/GOST_Urban # Online location of your book
+  url: https://github.com/worldbank/GOSTnets # Online location of your book
   path_to_book: docs # Optional path to your book, relative to the repository root
   branch: main # Which branch of the repository should be used when creating links (optional)
 

docs/_toc.yml

@@ -4,50 +4,15 @@
 format: jb-book
 root: README
 parts:
-  - caption: Documentation
-    chapters:
-      - file: api/GOSTurban.rst
-  - caption: Novel Urbanization
-    chapters:
-      - file: novel_context
-      - file: urbanization_comparison
   - caption: Tutorials
     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
+      - file: Tutorials/'Step 1 - Extract From OSM.ipynb'
+      - file: Tutorials/'Step 2 - Clean Network.ipynb'
+      - file: Tutorials/'Step 3 - Using your Graph.ipynb'
+      - file: Tutorials/'EXAMPLE Finding_links_between_pairs.ipynb'
+      - file: Tutorials/'EXAMPLE Fixing your road network.ipynb'
+      - file: Tutorials/'EXAMPLE Gravity Calculations.ipynb'
+  - caption: API Documentation
+    chapters:
+      - file: api/index.rst
+      - file: api/modules.rst

docs/api/GOSTnets.rst

@@ -0,0 +1,85 @@
+GOSTnets package
+================
+
+Submodules
+----------
+
+GOSTnets.calculate\_od\_raw module
+----------------------------------
+
+.. automodule:: GOSTnets.calculate_od_raw
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.conversion\_utils module
+---------------------------------
+
+.. automodule:: GOSTnets.conversion_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.core module
+--------------------
+
+.. automodule:: GOSTnets.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.fetch\_od module
+-------------------------
+
+.. automodule:: GOSTnets.fetch_od
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.fetch\_pois module
+---------------------------
+
+.. automodule:: GOSTnets.fetch_pois
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.load\_osm module
+-------------------------
+
+.. automodule:: GOSTnets.load_osm
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.network\_clean module
+------------------------------
+
+.. automodule:: GOSTnets.network_clean
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.optimization module
+----------------------------
+
+.. automodule:: GOSTnets.optimization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GOSTnets.osm\_parser module
+---------------------------
+
+.. automodule:: GOSTnets.osm_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: GOSTnets
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/modules.rst

@@ -1,7 +1,7 @@
-GOSTnets
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   GOSTnets
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   GOSTnets

pyproject.toml

@@ -38,7 +38,13 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pre-commit", "pytest", "pytest-cov", "tomli", "GOStnets[docs,osm,opt]"]
-docs = ["docutils==0.17.1", "jupyter-book>=1,<2"]
+docs = [
+	"docutils==0.17.1",
+	"jupyter-book>=1,<2",
+	"sphinxcontrib-apidoc>=0.4.0,<1",
+	"jupyter-cache>=0.6.0",
+	"nbconvert",
+]
 osm = ["gdal", "geopy", "boltons"]
 opt = ["pulp"]