Merge pull request #243 from joshuacortez/chore/update_contributing

butchtm · web-flow · commit 61e2fca3e380 · 2024-08-09T09:37:59.000+08:00
update contributing markdown
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -26,22 +26,14 @@ If you are reporting a bug, please include:
 ## Creating pull requests
 
 1. Fork the repo in Github or go to https://github.com/thinkingmachines/geowrangler/fork
-2. Install and enable `pre-commit` and `poetry`
+2. Set up the development environment following the instructions in [DEVELOPMENT](https://github.com/thinkingmachines/geowrangler/blob/master/DEVELOPMENT.md)
 
-```
-pip install poetry>=1.2.0 pre-commit
-pre-commit install
-poetry install
-poetry run pip install pip --upgrade
-poetry run pip install -e .
-```
-
-3. Make the necessary changes. See [Developing with nbdev](#developing-with-nbdev) for more info.
+3. Make the necessary contributions. See [Developing with nbdev](#developing-with-nbdev) for more info.
 
 4. Run the tests and ensure they all pass before submitting a PR. Also add tests whenever adding a new feature. Finally, clean up tests that are longer applicable.
 
 ```
-poetry run pytest --cov --cov-config=.coveragerc --cov-fail-under=80 -n auto
+pytest --cov --cov-config=.coveragerc --cov-fail-under=80 -n auto
 ```
 
 5. Commit and Submit PR for review
@@ -59,10 +51,18 @@ poetry run pytest --cov --cov-config=.coveragerc --cov-fail-under=80 -n auto
 Once the necessary changes are made, run the following to generate the python code.
 
 ```
-poetry run nbdev_export
-poetry run pre-commit run -a
-poetry run pre-commit run -a
+nbdev_export
 ```
-> Note: we are running `pre-commit` twice so that it reformats the modules to comply with the project's formatting/linting standards and the next run checks if it is already compliant. 
 
+## View contributions on documentation site and edit as needed
+
+1. Run nbdev_docs to create the HTML files via Quarto (can verify locally with some port: nbdev_preview --port 4327)
+    - Doc site automatically updates once a PR is merged (in Settings > Pages need to make sure [geowrangler.thinkingmachin.es](http://geowrangler.thinkingmachin.es/) is the domain as it defaults to [thinkingmachines.github.io](http://thinkingmachines.github.io/) after merges)
+2. Edit [notebooks/index.ipynb](https://github.com/thinkingmachines/geowrangler/blob/master/notebooks/index.ipynb) to edit the [doc homepage](https://geowrangler.thinkingmachin.es/)
+3. Edit [notebooks/sidebar.yml](https://github.com/thinkingmachines/geowrangler/blob/master/notebooks/sidebar.yml) to edit the left sidebar
 
+## Updating Google Colab links in notebooks
+  - In notebooks such as tutorial notebooks you may want to add a Google Colab link at the beginning of the notebook for easy accessibility.
+  - There is no automatic way yet to update this so it's a manual update of a markdown cell. Since the link points to a notebook in master, testing the Colab button is done after merging. Follow the sample below and replace the notebook name with your contributed notebook name.
+  - Sample for notebooks/14_datasets_nightlights.ipynb:
+[![](https://colab.research.google.com/assets/colab-badge.svg "Open in Colab button")](https://colab.research.google.com/github/thinkingmachines/geowrangler/blob/master/notebooks/14_datasets_nightlights.ipynb)
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -14,7 +14,7 @@ You can run geowrangler's jupyter notebooks to see how the different modules are
 * OS: Linux, MacOS, Windows Subsystem for Linux (WSL) on Windows
 
 * Requirements:
-   - python 3.8 or higher
+   - python 3.9 or higher
    - virtualenv, venv or conda for python environment virtualization
    - [quarto](https://quarto.org) to preview the documentation site locally
   
@@ -36,7 +36,7 @@ To generate and preview the documentation site on your local machine, you will n
 
 **Set-up with virtualenv**
 
-Set up your Python env with `virtualenv` and install pre-commits and the necessary python libs by running the following commands.
+Set up your Python env with `virtualenv` and install the necessary python libs by running the following commands.
 
 Remember to replace `<your-github-id>` in the github url below with your GitHub ID to clone from your fork.
 
@@ -64,7 +64,7 @@ conda deactivate # important to ensure libs from other envs aren't used
 conda activate geowrangler-env
 ```
 
-Then run the following to install the pre-commits and python libs.
+Then run the following to install the python libs.
 ```
 cd geowrangler # cd into your geowrangler local directory
 pip install -e ".[dev]"
diff --git a/mkdocs/docs/README.md b/mkdocs/docs/README.md
@@ -49,152 +49,4 @@ The documentation for [the package is available here](https://geowrangler.thinki
 
 If you want to learn more about **Geowrangler** and explore its inner workings, you can setup a local development environment. You can run geowrangler's jupyter notebooks to see how the different modules are built and how they work. 
 
-
-#### Pre-requisites
-
-* OS: Linux, MacOS, Windows Subsystem for Linux (WSL) on Windows
-
-* Requirements:
-   - python 3.7 or higher
-   - virtualenv, venv or conda for python environment virtualization
-   - poetry for dependency management
-
-#### Github Repo Fork
-
-If you plan to make contributions to geowrangler, we encourage you to
-[create your fork](https://github.com/thinkingmachines/geowrangler/fork) of the Geowrangler repo. 
-
-This will then allow you to push commits to your forked repo and 
-then create a Pull Request (PR) from your repo to the main geowrangler 
-repo for approval by geowrangler's maintainers.
-
-#### Development Installation
-
-We recommend creating a virtual python environment via [virtualenv](https://pypi.org/project/virtualenv/) or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html) for your development environment. Please see the relevant documentation for more details on installing these python environment managers. Afterward, continue the geowrangler setup instructions below.
-
-
-**Set-up with virtualenv**
-
-First, install `libgeos` ( version >=3.8 required for building pygeos/shapely) through the ff. commands. 
-
-*See [libgeos documentation](https://libgeos.org/usage/install/) for installation details on other systems.*
-
-```
-sudo apt update # updates package info
-sudo apt install build-essential # installs GCC
-sudo apt install libgeos-dev
-```
-
-Next, set-up your Python env with `virtualenv` and install pre-commits and the necessary python libs by running the following commands.
-
-Remember to replace `<your-github-id>` in the github url below with your GitHub ID to clone from your fork.
-
-```
-git clone https://github.com/<your-github-id>/geowrangler.git
-cd geowrangler
-virtualenv -p /usr/bin/python3.9 .venv
-source .venv/bin/activate
-pip install pre-commit poetry>=1.2.0
-pre-commit install
-poetry config --local installer.no-binary pygeos,shapely
-poetry install
-```
-
-You're all set! [Run the tests](#running-tests) to make sure everything was installed properly.
-
-Whenever you open a new terminal, you can `cd <your-local-geowrangler-folder>`
-and  run `poetry shell` to activate the geowrangler environment.
-
-**Set-up with conda**
-
-Run the following commands to set-up a conda env and install geos.
-
-```
-conda create -y -n geowrangler-env python=3.9 # replace geowrangler-env if you prefer a different env name
-conda deactivate # important to ensure libs from other envs aren't used
-conda activate geowrangler-env
-conda install -y geos
-```
-
-Then run the following to install the pre-commits and python libs.
-```
-cd geowrangler # cd into your geowrangler local directory
-pip install pre-commit poetry>=1.2.0
-pre-commit install
-poetry install
-```
-
-You're all set! [Run the tests](#running-tests) to make sure everything was installed properly.
-
-Whenever you open a new terminal, run `conda deactivate && conda activate geowrangler-env` to deactivate any conda env, and then activate the geowrangler environment.
-
-### Jupyter Notebook Development
-
-The code for the **geowrangler** python package resides in Jupyter notebooks located in the `notebooks` folder.
-
-Using [nbdev](https://nbdev.fast.ai), we generate the python modules residing in the `geowrangler` folder from code cells in jupyter notebooks marked with an `#export` comment. A `#default_exp <module_name>` comment at the first code cell of each notebook directs `nbdev` to put the code in a module named `<module_name>` in the `geowrangler` folder. 
-
-See the [nbdev cli](https://nbdev.fast.ai/cli.html) documentation for more details on the commands to generate the package as well as the documentation.
-### Running notebooks
-
-Run the following to view the jupyter notebooks in the `notebooks` folder
-
-```
-poetry run jupyter lab
-```
-### Generating and viewing the documentation site
-
-To generate and view the documentation site on your local machine, the quickest way is to setup [Docker](https://docs.docker.com/get-started/). The following assumes that you have setup docker on your system.
-```
-poetry run nbdev_docs --mk_readme False --force_all True
-docker-compose up jekyll
-```
-
-As an alternative if you don't want to use _Docker_ you can [install jekyll](https://jekyllrb.com/docs/installation/) to view the documentation site locally.
-
-`nbdev` converts notebooks within the `notebooks/` folder into a jekyll site.
-
-From this jekyll site, you can then create a static site.
-
-To generate the docs, run the following
-
-```
-
-poetry run nbdev_docs -mk_readme False --force_all True
-cd docs && bundle i && cd ..
-
-```
-
-To run the jekyll site, run the following
-
-```
-cd docs
-bundle exec jekyll serve
-```
-
-### Running tests
-
-We are using `pytest` as our test framework. To run all tests and generate a generate a coverage report, run the following.
-
-```
-poetry run pytest --cov --cov-config=.coveragerc -n auto
-```
-
-
-To run a single test or test file
-
-```shell
-# for a single test function
-poetry run pytest tests/test_grids.py::test_create_grids
-# for a single test file
-poetry run pytest tests/test_grids.py
-```
-### Contributing
-
-Please read [CONTRIBUTING.md](https://github.com/thinkingmachines/geowrangler/blob/master/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/thinkingmachines/geowrangler/blob/master/CODE_OF_CONDUCT.md) before anything.
-
-### Development Notes
-
-For more details regarding our development standards and processes, please see [our wiki](https://github.com/thinkingmachines/geowrangler/wiki/DeveloperNotes).
-
-
+Set up the development environment following the instructions in [DEVELOPMENT](https://github.com/thinkingmachines/geowrangler/blob/master/DEVELOPMENT.md)
