[doc] Generate the two flavors of the documentation (online and offline)

- Online flavor goes to the root.
- Offline flavor goes into an `offline` subdirectory.

[ci skip]

Author: Clément Le Provost

.jazzy.yaml

@@ -4,3 +4,21 @@ output: build/doc
 docset_path: ../docset
 hide_documentation_coverage: true
 skip_undocumented: true
+# Avoid putting the current date into the docs (this makes the diff quite noisy).
+# TODO: Jazzy does not support putting the Cocoapods version so far.
+copyright: "© Copyright 2016 [Algolia](https://www.algolia.com/). All rights reserved."
+readme: doc/include/reference.md
+custom_categories:
+    - name: API Client
+      children:
+        - Client
+        - Index
+        - Query
+        - BrowseIterator
+
+    - name: Auxiliary types
+      children:
+        - GeoRect
+        - IndexQuery
+        - LatLng
+        - LibraryVersion

doc/include/reference-offline.md

@@ -0,0 +1,9 @@
+
+
+# Algolia Search Offline API Client for Swift
+
+This is the reference documentation for the **Algolia Search Offline API Client for Swift**. You can always browse the latest version online at [Algolia Community](https://community.algolia.com/algoliasearch-client-swift/offline/).
+
+**Note:** The Offline API Client is an offline-enabled version, and a superset, of the regular [API Client](../index.html).
+
+**Note:** This documentation is automatically generated from sources. For an overview of how Algolia works, detailed setup and usage instructions, please refer to our [Documentation](https://www.algolia.com/doc), in particular to the [Swift API Client](https://www.algolia.com/doc/api-client/swift/) documentation.

doc/include/reference.md

@@ -0,0 +1,7 @@
+
+
+# Algolia Search API Client for Swift
+
+This is the reference documentation for the **Algolia Search API Client for Swift**. You can always browse the latest version online at [Algolia Community](https://community.algolia.com/algoliasearch-client-swift/).
+
+**Note:** This documentation is automatically generated from sources. For an overview of how Algolia works, detailed setup and usage instructions, please refer to our [Documentation](https://www.algolia.com/doc), in particular to the [Swift API Client](https://www.algolia.com/doc/api-client/swift/) documentation.

doc/maintenance.md

@@ -69,6 +69,14 @@ keep versioning aligned (there is only one version number for both flavors).
 
 - Edit the **release notes**: in GitHub, edit the tag and copy-paste the Change Log section for this release.
 
+- Update the **reference documentation**:
+
+    - Generate the documentation: `tools/make-doc.sh`
+
+    - Review it: `cd build/doc && git diff`
+
+    - Publish it: `git add . && git commit && git push`
+
 - Update the **external documentation** if necessary:
 
     - [Guides](https://www.algolia.com/doc/guides)

doc/reference.md

@@ -5,13 +5,16 @@ xcodebuild_arguments:
     - AlgoliaSearch.xcworkspace
     - -scheme
     - AlgoliaSearch-Offline-iOS
-output: build/doc
+output: build/doc/offline
 # Avoid putting the DocSet within the HTML docs.
 # WARNING: The path is relative to the output directory.
-docset_path: ../docset
+docset_path: ../../docset-offline
 hide_documentation_coverage: true
 skip_undocumented: true
-readme: doc/reference.md
+# Avoid putting the current date into the docs (this makes the diff quite noisy).
+# TODO: Jazzy does not support putting the Cocoapods version so far.
+copyright: "© Copyright 2016 [Algolia](https://www.algolia.com/). All rights reserved."
+readme: doc/include/reference-offline.md
 custom_categories:
     - name: API Client
       children:

offline.jazzy.yaml

@@ -0,0 +1,53 @@
+#!/usr/bin/env ksh
+
+set -e # fail on first error
+
+# Reflection.
+SELF_ROOT=$(cd $(dirname "$0") && pwd)
+PROJECT_ROOT=$(cd "$SELF_ROOT"/.. && pwd)
+
+GIT_REPO_NAME="algolia/algoliasearch-helper-swift"
+BRANCH_NAME="gh-pages"
+DST_DIR="$PROJECT_ROOT/build/doc"
+
+# Prepare the destination directory
+# ---------------------------------
+# If the destination directory exists, make sure that it's a Git checkout of the `gh-pages` branch.
+if [[ -d "$DST_DIR" ]]; then
+    branch_name=$(cd "$DST_DIR" && git rev-parse --abbrev-ref HEAD)
+    if [[ "$branch_name" != "$BRANCH_NAME" ]]; then
+        echo "ERROR: Directory '$DST_DIR' is not a checkout of the '$BRANCH_NAME' branch!" 1>&2
+        exit 1
+    fi
+    pwd=$(pwd)
+    # Clean the Git checkout.
+    echo "Git checkout found; cleaning"
+    cd "$DST_DIR" && git clean -f
+    cd "$pwd"
+# Otherwise, create it.
+else
+    echo "No Git checkout found; cloning"
+    mkdir -p $(dirname "$DST_DIR")
+    git clone [email protected]:$GIT_REPO_NAME -b "$BRANCH_NAME" --single-branch "$DST_DIR"
+fi
+
+# Make the documentation
+# ----------------------
+# Clean the destination directory.
+# NOTE: We don't use Jazzy's `--clean` option because it deletes the destination directory; we want to preserve the
+# Git checkout.
+echo "Cleaning destination directory"
+rm -rf "$DST_DIR"/*
+
+# Generate the documentations with [Jazzy](https://github.com/realm/jazzy).
+cd "$PROJECT_ROOT"
+# Online flavor -> root directory.
+echo "# Generating online flavor"
+jazzy --config .jazzy.yaml
+# Offline flavor -> `offline` subdirectory.
+echo "# Generating offline flavor"
+jazzy --config offline.jazzy.yaml
+
+cp "$PROJECT_ROOT/LICENSE" "$DST_DIR/LICENSE.md"
+
+echo 'Done. Git diff then add and commit.'