Reorganized docs and renamed example project

Main change to the docs was to turn "Getting Started" into a section with multiple child pages. 

And now that the example project isn't specific to PySpark but rather to "getting started", it's now called "getting-started". And renamed the project application from "pyspark-example" to "spark-example".

Author: rjrudin

.github/workflows/jekyll-gh-pages.yml

@@ -3,7 +3,7 @@ name: Deploy Jekyll with GitHub Pages dependencies preinstalled
 
 on:
   # Runs on pushes targeting the default branch.
-  # TODO This will be changed to master before the 1.0 release.
+  # TODO This will be changed to master before the 2.0 release.
   push:
     branches: ["develop"]
 

CONTRIBUTING.md

@@ -85,7 +85,7 @@ This will produce a single jar file for the connector in the `./build/libs` dire
 
 You can then launch PySpark with the connector available via:
 
-    pyspark --jars build/libs/marklogic-spark-connector-1.0-SNAPSHOT.jar
+    pyspark --jars build/libs/marklogic-spark-connector-2.0-SNAPSHOT.jar
 
 The below command is an example of loading data from the test application deployed via the instructions at the top of 
 this page. 

build.gradle

@@ -7,7 +7,7 @@ plugins {
 }
 
 group 'com.marklogic'
-version '1.0-SNAPSHOT'
+version '2.0-SNAPSHOT'
 
 java {
   sourceCompatibility = 1.8

caddy/config/Caddyfile

@@ -10,7 +10,7 @@
     }
 }
 
-# For the examples/pyspark application.
+# For the examples/getting-started application.
 :8820 {
     reverse_proxy bootstrap_3n.local:8020 node2.local:8020 node3.local:8020 {
       # Required for MLCP to work; "ip_hash" also works.

docker-compose.yaml

@@ -20,7 +20,7 @@ services:
       - 8015:8815
       # For running performance tests against quick-table data
       - 8009:8809
-      # For the pyspark-example project
+      # For the getting-started project
       - 8020:8820
     networks:
       - external_net

docs/configuration.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Configuration Reference
-nav_order: 7
+nav_order: 5
 ---
 
 The MarkLogic Spark connector has 3 sets of configuration options - connection options, reading options, and writing 
 options. Each set of options is defined in a separate table below.
 
-# Connection options
+## Connection options
 
 These options define how the connector connects and authenticates with MarkLogic.
 
@@ -30,7 +30,7 @@ These options define how the connector connects and authenticates with MarkLogic
 | spark.marklogic.client.sslHostnameVerifier | Either `any`, `common`, or `strict`. |
 | spark.marklogic.client.uri | Shortcut for setting the host, port, username, and password when using `basic` or `digest` authentication. See below for more information. |
 
-## Connecting with a client URI
+### Connecting with a client URI
 
 The `spark.marklogic.client.uri` is a convenience for the common case of using `basic` or `digest` authentication.
 It allows you to specify username, password, host, and port via the following syntax:
@@ -50,7 +50,7 @@ Using this convenience can provide a much more succinct set of options - for exa
 
 ```
 df = spark.read.format("com.marklogic.spark")\
-    .option("spark.marklogic.client.uri", "pyspark-example-user:password@localhost:8020")\
+    .option("spark.marklogic.client.uri", "spark-example-user:password@localhost:8020")\
     .option("spark.marklogic.read.opticDsl", "op.fromView('example', 'employee')")\
     .load()
 ```
@@ -59,7 +59,7 @@ Note that if the username or password contain either a `@` or a `:` character, y
 [percent encoding](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) into the correct character 
 triplet. For example, a password of `sp@r:k` must appear in the `spark.marklogic.client.uri` string as `sp%40r%3Ak`. 
 
-# Read options
+## Read options
 
 These options control how the connector reads data from MarkLogic. See [the guide on reading](reading.md) for more 
 information on how data is read from MarkLogic.
@@ -70,9 +70,7 @@ information on how data is read from MarkLogic.
 | spark.marklogic.read.numPartitions | The number of Spark partitions to create; defaults to `spark.default.parallelism` .               |
 | spark.marklogic.read.batchSize | Approximate number of rows to retrieve in each call to MarkLogic; defaults to 10000.              |
 
-## Schema support
-
-# Write options
+## Write options
 
 These options control how the connector writes data to MarkLogic. See [the guide on writing](writing.md) for more 
 information on how data is written to MarkLogic.

docs/getting-started-pyspark.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+has_children: true
+permalink: /docs/getting-started
+---
+
+This guide provides instructions on using the MarkLogic Spark connector with multiple popular Spark environments. 
+Before trying the connector in any of these environments, please [follow the instructions in the Setup guide](setup.md)
+to obtain the connector and deploy an example application to MarkLogic.
+
+For environments not yet listed here, the process for using the connector will typically involve determining how a 
+connector JAR file is included in the Spark environment. Please see the documentation for your specific Spark 
+environment for instructions on how to accomplish that goal.

docs/getting-started/getting-started.md

@@ -1,23 +1,31 @@
 ---
 layout: default
-title: Getting Started with Jupyter
-nav_order: 4
+title: Jupyter
+parent: Getting Started
+nav_order: 3
 ---
 
 [Project Jupyter](https://jupyter.org/) provides a set of tools for working with notebooks, code, and data. The 
 MarkLogic Spark connector can be easily integrated into these tools to allow users to access and analyze data in 
 MarkLogic. 
 
+Before going further, be sure you've followed the instructions in the [setup guide](setup.md) for
+obtaining the connector and deploying an example application to MarkLogic.
+
+## Install Jupyter
+
 To get started, install either [JupyterLab or Jupyter Notebook](https://jupyter.org/install). Both of these tools
 allow you to work with the connector in the same fashion. The rest of this guide will assume the use of Jupyter 
 Notebook, though the instructions will work for JupyterLab as well. 
 
 Once you have installed, started, and accessed Jupyter Notebook in your web browser - in a default Notebook 
 installation, you should be able to access it at http://localhost:8889/tree - click on "New" in the upper right hand 
-corner of the Notebook interface and select "Python 3 (ipykernel)" to create a new notebook. 
+corner of the Notebook interface and select "Python 3 (ipykernel)" to create a new notebook.
 
-In the first cell in the notebook, enter the following to allow Jupyter Notebook to access the MarkLogic Spark connector
-and also to initialize Spark:
+## Using the connector
+
+In the first cell in the notebook created above, enter the following to allow Jupyter Notebook to access the MarkLogic 
+Spark connector and also to initialize Spark:
 
 ```
 import os
@@ -33,8 +41,7 @@ The path of `/path/to/marklogic-spark-connector-2.0.0.jar` should be changed to
 jar on your filesystem. You are free to customize the `spark` variable in any manner you see fit as well. 
 
 Now that you have an initialized Spark session, you can run any of the examples found in the 
-[Getting Started with PySpark](getting-started-pyspark.md) guide. 
-
+[guide for using PySpark](pyspark.md).