Merge pull request #465 from azavea/rde/feature/docs

Documentation

.gitignore

@@ -104,9 +104,6 @@ deployment/ansible/*.retry
 *~
 .#*
 
-# Generated pb2 files
-rastervision/protos/**/*_pb2.py
-
 # Vim
 .*.sw*
 

.travis/test

@@ -1,7 +1,13 @@
 #!/bin/bash
 
+# Check no uncompiled protobufs
+docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu $(pwd)/scripts/compile
+if [ ! -z "$(git status --porcelain)" ]; then
+    echo "Protobuf files need to be compiled. Run scripts/compile."
+    exit 1
+fi
+
 docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu rm -f $(pwd)/.coverage $(pwd)/coverage.xml
 docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu $(pwd)/scripts/style_tests && \
-docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu $(pwd)/scripts/compile && \
 docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu $(pwd)/scripts/unit_tests && \
 docker run -w $(pwd) -v $(pwd):$(pwd) --rm -it raster-vision-cpu $(pwd)/scripts/integration_tests

Dockerfile-cpu

@@ -26,6 +26,10 @@ ENV PYTHONPATH=/opt/src:/opt/tf-models:/opt/tf-models/slim:$PYTHONPATH
 COPY ./requirements-dev.txt /opt/src/requirements-dev.txt
 RUN pip install -r requirements-dev.txt
 
+# Install docs/requirements.txt
+COPY ./docs/requirements.txt /opt/src/docs/requirements.txt
+RUN pip install -r docs/requirements.txt
+
 # Install extras_requirements.json
 # Don't install tensorflow
 COPY ./extras_requirements.json /opt/src/extras_requirements.json

Dockerfile-gpu

@@ -26,6 +26,10 @@ ENV PYTHONPATH=/opt/src:/opt/tf-models:/opt/tf-models/slim:$PYTHONPATH
 COPY ./requirements-dev.txt /opt/src/requirements-dev.txt
 RUN pip install -r requirements-dev.txt
 
+# Install docs/requirements.txt
+COPY ./docs/requirements.txt /opt/src/docs/requirements.txt
+RUN pip install -r docs/requirements.txt
+
 # Install extras_requirements.json
 # Don't install tensorflow
 COPY ./extras_requirements.json /opt/src/extras_requirements.json

README.md

@@ -8,7 +8,7 @@
 
 ![Release Coming October 2018](/release-notice.png "RELEASE COMING OCTOBER 2018")
  
-![Raster Vision Logo](/logo_dark.png)
+![Raster Vision Logo](/docs/_static/logo_dark.png)
  
 
 The overall goal of Raster Vision is to make it easy to train and run machine learning models over imagery, including aerial and satellite imagery. It includes functionality for making training data, training models, making predictions, and evaluating models for the tasks of object detection (implemented via the Tensorflow Object Detection API), chip classificaiton (implemented via Keras), and semantic segmentation (implemented via Deep Lab).  It also supports running experimental workflows using AWS Batch. The library is designed to be easy to extend to new data sources, machine learning tasks, and machine learning implementation.

docker/console

@@ -46,6 +46,10 @@ do
         RUNTIME="--runtime=nvidia"
         shift # past argument
         ;;
+        --docs)
+        DOCS="-p 8000:8000"
+        shift # past argument
+        ;;
         --name)
         shift
         NAME="--name $1"
@@ -61,7 +65,7 @@ set -- "${POSITIONAL[@]}" # restore positional parameters
 
 if [ "${BASH_SOURCE[0]}" = "${0}" ]
 then
-    docker run ${RUNTIME} ${NAME} --rm -it ${TENSORBOARD} ${AWS} \
+    docker run ${RUNTIME} ${NAME} --rm -it ${TENSORBOARD} ${AWS} ${DOCS} \
         -v ${HOME}/.rastervision:/root/.rastervision \
         -v "$PROJECT_ROOT":/opt/src \
         -v ${RASTER_VISION_DATA_DIR}:/opt/data \

docker/doc-server

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -e
+
+if [[ -n "${RASTER_VISION_DEBUG}" ]]; then
+    set -x
+fi
+
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ] ; do SOURCE="$(readlink "$SOURCE")"; done
+SCRIPTS_DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+PROJECT_ROOT="$( cd -P "$( dirname "$SCRIPTS_DIR" )" && pwd )"
+
+function usage() {
+    echo -n \
+         "Usage: $(basename "$0") (--local|--remote)
+Run a livehtml server to serve out documentation
+"
+}
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]
+then
+        docker run --rm -it \
+               -v "$PROJECT_ROOT":/opt/src \
+               -p 8000:8000 \
+               raster-vision-cpu \
+               /bin/bash -c \
+               "cd docs && make livehtml"
+    fi
+fi

docs/CONTRIBUTING.rst

@@ -8,10 +8,10 @@ as it will make the process of accepting changes smoother.
 Everyone who contributes code to Raster Vision will be asked to sign the
 Azavea CLA, which is based off of the Apache CLA.
 
-1. Download a copy of the [Raster Vision Individual Contributor License
-   Agreement](docs/cla/2018_04_17-Raster-Vision-Open-Source-Contributor-Agreement-Individual.pdf)
-   or the [Raster Vision Corporate Contributor License
-   Agreement](docs/cla/2018_04_18-Raster-Vision-Open-Source-Contributor-Agreement-Corporate.pdf)
+1. Download a copy of the `Raster Vision Individual Contributor License
+   Agreement <_static/cla/2018_04_17-Raster-Vision-Open-Source-Contributor-Agreement-Individual.pdf>`_
+   or the `Raster Vision Corporate Contributor License
+   Agreement <_static/cla/2018_04_18-Raster-Vision-Open-Source-Contributor-Agreement-Corporate.pdf>`_
 
 2. Print out the CLAs and sign them, or use PDF software that allows placement of a signature image.
 

docs/Makefile

@@ -13,7 +13,7 @@ help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 livehtml:
-	sphinx-autobuild `pwd` `pwd`/_build/html
+	sphinx-autobuild --host 0.0.0.0 `pwd` `pwd`/_build/html
 
 .PHONY: help Makefile
 

docs/README.md

@@ -0,0 +1,19 @@
+## Raster Vision Documentation
+
+This directory contains the Sphinx documentation for Raster Vision.
+
+### Developing
+
+All commands are issued in this directory.
+
+You'll need to install the required packages:
+
+```
+> pip install -r requirements.txt
+```
+
+To run a live local server that updates with changes, run:
+
+```
+> make livehtml
+```

docs/_static/rastervision.css

@@ -0,0 +1,46 @@
+.underline {
+  text-decoration: underline;
+}
+
+body, pre, code {
+  font-family: "Menlo", "Ubuntu Mono", "Consolas", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", monospace;
+  font-size: 16px;
+}
+
+div.body {
+    padding: 0px 75px;
+}
+
+div.admonition, div.topic {
+  padding: 15px;
+  font-size: 14px;
+}
+
+div.admonition p.admonition-title,
+div.topic p.topic-title {
+  font-weight: bold;
+  font-size: 18px;
+  margin: 0 0 10px 0;
+  padding: 0;
+  line-height: 1;
+  display: inline;
+}
+
+div.admonition, div.note {
+  background-color: #fffff0;
+  border-color: #f0f0a8;
+}
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}