Merge branch 'main' into mdtanker-patch-3

CHANGELOG.md

@@ -7,6 +7,13 @@ with commit parsing of [angular commits](https://github.com/angular/angular.js/b
 ### 📦️ Build
 ### 🧰 Chores / Maintenance
 * remove pre-commit updates from changelog ([`611ff84`](https://github.com/mdtanker/polartoolkit/commit/611ff84c3ba5a5a31f6e4870f231dcd74c1f7053))
+### 📖 Documentation
+* reuse readme material in RTD index ([`8791e96`](https://github.com/mdtanker/polartoolkit/commit/8791e9604e007417d4e7240a37fdf7d17f98000c))
+### ✏️ Formatting
+* auto style fixes from ruff/pylint ([`e1efbab`](https://github.com/mdtanker/polartoolkit/commit/e1efbab1eded88ebb42b256a09c4198e93f16842))
+### Other
+*  ([`49e95cb`](https://github.com/mdtanker/polartoolkit/commit/49e95cb854a9938095cf277d872db148a84fce5c))
+*  ([`cb7ee9d`](https://github.com/mdtanker/polartoolkit/commit/cb7ee9d64117a96e0220b9d2ff3f90c1f1b71f7d))
 
 
 ## v0.3.3 (2024-04-23)

README.md

@@ -5,47 +5,45 @@
 <a href="https://polartoolkit.readthedocs.io"><strong>Documentation Link</strong></a>
 </p>
 
-<!-- SPHINX-START1 -->
+<!-- SPHINX-START-proj-desc -->
+
+**PolarToolkit** (formerly known as Antarctic-Plots) is a Python package with
+the goal of making Polar (i.e. Antarctic, Arctic, Greenland) research more
+efficient, reproducible, and accessible. The software does this by providing:
+
+- Convenient functions for downloading and pre-processing a wide range of
+  commonly used polar datasets
+- Tools for common geospatial tasks (i.e. changing data resolution, subsetting
+  data by geographic regions)
+- Code to easily create publication-quality maps, data profiles, and
+  cross-sections
+
+Additionally, **PolarToolkit** provides an easy means for exploring datasets
+with pre-defined or interactively-chosen geographic regions.
+
+<!-- SPHINX-END-proj-desc -->
+
+<!-- SPHINX-START-badges -->
 
 <p align="center">
 <a href="https://mybinder.org/v2/gh/mdtanker/polartoolkit-binder/main?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252Fmdtanker%252Fpolartoolkit%26urlpath%3Dtree%252Fpolartoolkit%252Fdocs%252Fgallery%26branch%3Dmain">
  <img src="https://mybinder.org/badge_logo.svg" alt="Binder link"></a>
  </p>
 
 <p align="center">
-<a href="https://pypi.python.org/pypi/polartoolkit">
-<img
-src="https://img.shields.io/pypi/v/polartoolkit?style=flat-square"
-alt="Latest version on PyPI"
-/>
-</a>
-<a href="https://github.com/conda-forge/polartoolkit-feedstock">
-<img
-src="https://img.shields.io/conda/vn/conda-forge/polartoolkit.svg?style=flat-square"
-alt="Latest version on conda-forge"
-/>
-</a>
-<a href="https://codecov.io/gh/mdtanker/polartoolkit">
-<img
-src="https://img.shields.io/codecov/c/github/mdtanker/polartoolkit/main.svg?style=flat-square"
-alt="Test coverage status"
-/>
+<a href="https://pypi.python.org/pypi/polartoolkit"><img src="https://img.shields.io/pypi/v/polartoolkit?style=flat-square"
+alt="Latest version on PyPI"/></a>
+<a href="https://github.com/conda-forge/polartoolkit-feedstock"><img src="https://img.shields.io/conda/vn/conda-forge/polartoolkit.svg?style=flat-square"alt="Latest version on conda-forge"/></a>
+<a href="https://codecov.io/gh/mdtanker/polartoolkit"><img src="https://img.shields.io/codecov/c/github/mdtanker/polartoolkit/main.svg?style=flat-square" alt="Test coverage status"/></a>
+</p>
 
 <p align="center">
-<a href="https://pypi.org/project/polartoolkit/">
-<img src="https://img.shields.io/pypi/pyversions/polartoolkit?style=flat-square"
-alt="Compatible Python versions."
-/>
-</a>
-<a href="https://zenodo.org/badge/latestdoi/475677039">
-<img src="https://zenodo.org/badge/475677039.svg?style=flat-square"
-alt="Zenodo DOI"
-/>
-</a>
+<a href="https://pypi.org/project/polartoolkit/"><img src="https://img.shields.io/pypi/pyversions/polartoolkit?style=flat-square" alt="Compatible Python versions."/></a>
+<a href="https://zenodo.org/badge/latestdoi/475677039"><img src="https://zenodo.org/badge/475677039.svg?style=flat-square" alt="Zenodo DOI"/></a>
 <a href='https://readthedocs.org/projects/polartoolkit/'><img src='https://readthedocs.org/projects/polartoolkit/badge/?version=latest&style=flat-square' alt='Documentation Status' /></a>
  </p>
 
-<!-- SPHINX-END1 -->
+<!-- SPHINX-END-badges -->
 
 ![](docs/cover_fig.png)
 
@@ -66,7 +64,7 @@ I welcome any feedback, ideas, or contributions! Please contact us on the
 or submit an [issue on GitHub](https://github.com/mdtanker/polartoolkit/issues)
 for problems or feature ideas.
 
-<!-- SPHINX-START2 -->
+<!-- SPHINX-START-long-desc -->
 
 The **PolarToolkit** python package provides some basic tools to help in
 conducting polar research. You can use it to download common datasets (i.e.
@@ -89,7 +87,72 @@ a feature request through
 - Include more datasets to aid in downloading and storage.
 - Additional projections and possible support for the Arctic region as well.
 
-<!-- SPHINX-END2 -->
+<!-- SPHINX-END-long-desc -->
+
+## Installation
+
+There are 3 main ways to install `polartoolkit`. We show them here in order of
+simplest to hardest.
+
+### Conda / Mamba
+
+The easiest way to install this package and it's dependencies is with conda or
+mamba into a new virtual environment:
+
+```
+mamba create --name polartoolkit --yes --force polartoolkit
+```
+
+And activate the environment:
+
+```
+conda activate polartoolkit
+```
+
+Note that `conda` and `mamba` are interchangeable.
+
+### Pip
+
+Instead, you can use pip to install `polartoolkit`, but first you need to
+install a few dependencies with conda. This is because `PyGMT` `GeoPandas`, and
+`Cartopy` all rely on C packages, which can only be install with conda/mamba and
+not with pip.
+
+To create a new virtual environment:
+
+```
+mamba create --name polartoolkit --yes --force pygmt geopandas cartopy
+```
+
+And activate the environment, followed by using `pip` to install `polartoolkit`:
+
+```
+mamba activate polartoolkit
+pip install polartoolkit
+```
+
+To install the optional dependencies of `polartoolkit`, use this instead:
+
+```
+`pip install polartoolkit[all]`
+```
+
+### Development version
+
+You can use pip, with the above created environment, to install the latest
+source from GitHub:
+
+```
+pip install git+https://github.com/mdtanker/polartoolkit.git
+```
+
+Or you can clone the repository and install:
+
+```
+git clone https://github.com/mdtanker/polartoolkit.git
+cd polartoolkit
+pip install .
+```
 
 ## How to contribute
 

docs/index.md

@@ -1,10 +1,13 @@
 # PolarToolkit
 
-Helpful tools for polar researchers
+```{include} ../README.md
+:start-after: <!-- SPHINX-START-proj-desc -->
+:end-before: <!-- SPHINX-END-proj-desc -->
+```
 
 ```{include} ../README.md
-:start-after: <!-- SPHINX-START1 -->
-:end-before: <!-- SPHINX-END1 -->
+:start-after: <!-- SPHINX-START-badges -->
+:end-before: <!-- SPHINX-END-badges -->
 ```
 
 ```{image} cover_fig.png
@@ -21,8 +24,8 @@ This means that we are still adding a lot of new features and sometimes we make
 
 
 ```{include} ../README.md
-:start-after: <!-- SPHINX-START2 -->
-:end-before: <!-- SPHINX-END2 -->
+:start-after: <!-- SPHINX-START-long-desc -->
+:end-before: <!-- SPHINX-END-long-desc -->
 ```
 
 
@@ -130,4 +133,4 @@ Citations help support our work
     :expand:
 ```
 :::
-::::
+::::