Merge pull request stac-utils#27 from azavea/rde/fix/stac_io_docs

Doc updates and fixes in preparation for 0.3 release

Author: lossyrob

.flake8

@@ -0,0 +1,12 @@
+[flake8]
+max-line-length = 100
+
+## IGNORES
+
+# E127: flake8 reporting incorrect continuation line indent errors
+# on multi-line and multi-level indents
+
+# W503: flake8 reports this as incorrect, and scripts/format_code
+# changes code to it, so let format_code win.
+
+ignore = E127,W503

.gitignore

@@ -19,7 +19,8 @@ docs/_build/
 
 .ipynb_checkpoints/
 
-tutorials/pystac-example*
-tutorials/spacenet-stac/
-tutorials/spacenet-cog-stac/
-tutorials/data/
+docs/tutorials/pystac-example*
+docs/tutorials/spacenet-stac/
+docs/tutorials/spacenet-cog-stac/
+docs/tutorials/data/
+docs/quickstart_stac/

.travis.yml

@@ -11,6 +11,7 @@ install:
   - pip install -r requirements-dev.txt
 
 script:
+  - .travis/style_checks
   - python -m unittest discover tests/
 
 deploy:

.travis/style_checks

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+set -e
+
+if [[ -n "${PYSTAC_DEBUG}" ]]; then
+    set -x
+fi
+
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ] ; do SOURCE="$(readlink "$SOURCE")"; done
+TRAVIS_DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+SRC_DIR="$( cd -P "$( dirname "TRAVIS_DIR" )" && pwd )"
+
+function usage() {
+    echo -n \
+"Usage: $(basename "$0")
+Test that code is compliant with yapf (code formatter) and flake8.
+"
+}
+
+
+if [ "${1:-}" = "--help" ]; then
+    usage
+else
+    echo $SRC_DIR
+
+    echo "Checking that library code is consistent with flake8..."
+    flake8 "$SRC_DIR/pystac"
+
+    echo "Checking that test code is consistent with flake8..."
+    flake8 "$SRC_DIR/tests"
+
+    # Exit code of 1 if yapf has a non-empty diff
+    # (ie. scripts/format_code needs to be run)
+    echo "Checking that code is consistent with yapf..."
+    if !(yapf -dpr "$SRC_DIR/pystac" > /dev/null &&
+             yapf -dpr "$SRC_DIR/tests" > /dev/null); then
+        echo "Code has not been formatted by yapf."
+        exit 1
+    fi
+fi

CHANGELOG.md

@@ -1,5 +1,5 @@
 # Changelog
 
-## [v0.1.0] - 2019-01-13
+## [v0.3.0] - 2019-10-31
 
-Initial Release
+Initial release.

README.md

@@ -35,7 +35,7 @@ The table below shows the corresponding versions between pystac and STAC:
 
 | pystac | STAC  |
 | ------ | ----  |
-| 0.2.x  | 0.8.x |
+| 0.3.x  | 0.8.x |
 
 ## Documentation
 
@@ -49,18 +49,57 @@ To ensure development libraries are installed, install everything in `requiremen
 > pip install -r requirements-dev.txt
 ```
 
+### Unit Tests
+
 Unit tests are in the `tests` folder. To run unit tests, use `unittest`:
 
 ```
 > python -m unittest discover tests
 ```
 
-## Running the tutorials
+### Code quality checks
+
+PySTAC uses [flake8](http://flake8.pycqa.org/en/latest/) and [yapf](https://github.com/google/yapf) for code formatting and style checks.
+
+To run the flake8 style checks:
+
+```
+> flake8 pystac
+> flake8 tests
+```
 
-There are tutorials written as jupyter notebooks in the `tutorials` folder. To run them, run a jupyter notebook with the `tutorials` directory as the notebook directory:
+To format code:
 
 ```
-> PYTHONPATH=`pwd`:$PYTHONPATH jupyter notebook --ip 0.0.0.0 --port 8888 --notebook-dir=tutorials
+> yapf -ipr pystac
+> yapf -ipr tests
+```
+
+You could also run the `.travis/style_checks` script to check flake8 and yapf.
+
+### Documentation
+
+To build and develop the documentation locally, make sure sphinx is available (which is installed with `requirementts-dev.txt`), and use the Makefile in the docs folder:
+
 ```
+> cd docs
+> make html
+> make livehtml
+```
+
+Use 'make' without arguments to see a list of available commands.
+
+
+
+## Runing the quickstart and tutorials
+
+There is a quickstart and tutorials written as jupyter notebooks in the `docs/tutorials` folder.
+To run the notebooks, run a jupyter notebook with the `docs` directory as the notebook directory:
+
+```
+> PYTHONPATH=`pwd`:$PYTHONPATH jupyter notebook --ip 0.0.0.0 --port 8888 --notebook-dir=docs
+```
+
+You can then navigate to the notebooks and execute them.
 
 Requires [Jupyter](https://jupyter.org/) be installed.

docs/Makefile

@@ -12,7 +12,7 @@ help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 livehtml:
-	sphinx-autobuild --host 0.0.0.0 ${SOURCEDIR} $(BUILDDIR)/html -d _build/doctrees
+	sphinx-autobuild -z ../pystac --host 0.0.0.0 ${SOURCEDIR} $(BUILDDIR)/html -d _build/doctrees
 
 .PHONY: help Makefile