Creating documentation (#61)

* osm_parser doc-strings

* calculate_od_raw doc-strings

* fetch_pois doc-strings

* style network_clean.py

* doc-strings conversion_utils.py

* doc-strings graphtool.py

* doc-strings optimization.py

* doc-strings fetch_od.py

* doc-strings load_osm.py

* doc-strings core.py

* symlink the tutorials dir for docs

* re-org the docs

* readme symlink

* move api docs pages

* update gitignore

* fix symlinks

* add some pre-commit hooks

* reorg for docs

* rename to remove spaces and clean notebook outputs

* more space removal and notebook cleaning

* revisions to toc and tutorial

* Remove auto-generated content from version control

---------

Co-authored-by: Gabriel Stefanini Vicente <[email protected]>

.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

.gitignore

@@ -114,3 +114,10 @@ Tutorial/tutorial_data/rek_grid_pop_gravity.shx
 
 # ignore the version file
 *_version.py*
+
+# ignore the generated sphinx conf.py file
+# we generate it during the doc build using jupyter-book from _conf.py
+docs/conf.py
+docs/api/GOSTnets.rst
+docs/api/modules.rst
+_build/

.pre-commit-config.yaml

@@ -10,6 +10,9 @@ repos:
           - id: check-added-large-files
           - id: check-ast
           - id: check-json
+          - id: check-symlinks
+          - id: destroyed-symlinks
+          - id: check-toml
           - id: detect-aws-credentials
             args: [--allow-missing-credentials]
           - id: detect-private-key

README.md

@@ -107,26 +107,6 @@ pip install GOSTnets[opt]
 pip install GOSTnets[dev]
 ```
 
-## Documentation
-
-Documentation available at [readthedocs](https://GOSTnets.readthedocs.io/)
-
-Plenty of examples and tutorials using Jupyter Notebooks live inside of the Implementations folder within the [GOST_PublicGoods Github repo](https://github.com/worldbank/GOST_PublicGoods)
-
-### how to autobuild docs
-
-in the docs dir, run:
-
-```shell
-sphinx-apidoc -f -o source/ ../GOSTnets
-```
-
-in the docs dir, run:
-
-```shell
-make html
-```
-
 ## Usage
 
 Every function contains a docstring which can be brought up in use to check the inputs for various functions. For example: