Skip to content
This repository was archived by the owner on Jan 31, 2022. It is now read-only.

Commit ea2a29e

Browse files
author
Clément Le Provost
committed
[doc] Publish Javadoc documentation to GitHub Pages
`tools/make-doc.sh` generates the documentation for both flavors, ready to push to the `gh-pages` branch. [ci skip]
1 parent 93a408c commit ea2a29e

File tree

6 files changed

+78
-3
lines changed

6 files changed

+78
-3
lines changed

‎algoliasearch/build-offline.gradle‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ ext {
2525
PUBLISH_ARTIFACT_ID = "algoliasearch-offline-android"
2626
PUBLISH_NAME = "Algolia Search API Client for Android (offline flavor)"
2727
PUBLISH_DESCRIPTION = "This Android library lets you easily use the Algolia Search API from your Android Application, with additional offline capabilities. It wraps the Algolia Search REST API and the Algolia Search Offline Core."
28+
DOC_DIR = "build/doc/offline"
29+
DOC_TITLE = "Algolia Search Offline API Client for Android"
30+
DOC_OVERVIEW = "../doc/include/reference-offline.html"
2831
}
2932

3033
apply from: "common.gradle"

‎algoliasearch/build-online.gradle‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ ext {
2525
PUBLISH_ARTIFACT_ID = "algoliasearch-android"
2626
PUBLISH_NAME = "Algolia Search API Client for Android"
2727
PUBLISH_DESCRIPTION = "This Android library lets you easily use the Algolia Search API from your Android Application. It wraps the Algolia Search REST API."
28+
DOC_DIR = "build/doc"
29+
DOC_TITLE = "Algolia Search API Client for Android"
30+
DOC_OVERVIEW = "../doc/include/reference.html"
2831
}
2932

3033
apply from: "common.gradle"

‎algoliasearch/common.gradle‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -95,12 +95,13 @@ dependencies {
9595
// Compile docs.
9696
task javadoc(type: Javadoc) {
9797
source = android.sourceSets.main.java.srcDirs
98+
destinationDir = new File(projectDir, DOC_DIR)
99+
title = DOC_TITLE
98100
options.memberLevel = JavadocMemberLevel.PUBLIC
101+
options.noTimestamp = true // avoid noisy diffs
102+
options.overview = DOC_OVERVIEW
99103
classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
100104
classpath += configurations.javadoc
101-
// NOTE: We always recompile from scratch because this task is shared between the online and offline flavors,
102-
// and we don't want offline classes to be included in the online doc.
103-
delete destinationDir
104105
}
105106

106107
// Package docs into a jar.

‎doc/include/reference-offline.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
<body>
3+
<p>This is the reference documentation for the <strong>Algolia Search Offline API Client for Android</strong>. You can always browse the latest version online at <a href="https://community.algolia.com/algoliasearch-client-android/offline/" target="_top">Algolia Community</a>.</p>
4+
5+
<p><strong>Note:</strong> The Offline API Client is an offline-enabled version, and a superset, of the regular <a href="../index.html" target="_top">API Client</a>.</p>
6+
7+
<p><strong>Note:</strong> This documentation is automatically generated from sources. For an overview of how Algolia works, detailed setup and usage instructions, please refer to our <a href="https://www.algolia.com/doc" target="_top">Documentation</a>, in particular to the <a href="https://www.algolia.com/doc/api-client/android/" target="_top">Android API Client</a> documentation.</p>
8+
</body>

‎doc/include/reference.html‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
<body>
3+
<p>This is the reference documentation for the <strong>Algolia Search API Client for Android</strong>. You can always browse the latest version online at <a href="https://community.algolia.com/algoliasearch-client-android/" target="_top">Algolia Community</a>.</p>
4+
5+
<p><strong>Note:</strong> This documentation is automatically generated from sources. For an overview of how Algolia works, detailed setup and usage instructions, please refer to our <a href="https://www.algolia.com/doc" target="_top">Documentation</a>, in particular to the <a href="https://www.algolia.com/doc/api-client/android/" target="_top">Android API Client</a> documentation.</p>
6+
</body>

‎tools/make-doc.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/usr/bin/env ksh
2+
3+
set -e # fail on first error
4+
5+
# Reflection.
6+
SELF_ROOT=$(cd $(dirname "$0") && pwd)
7+
PROJECT_ROOT=$(cd "$SELF_ROOT"/.. && pwd)
8+
9+
GIT_REPO_URL=$(cd "$PROJECT_ROOT" && git remote get-url origin)
10+
BRANCH_NAME="gh-pages"
11+
DST_DIR="$PROJECT_ROOT/algoliasearch/build/doc"
12+
13+
# Prepare the destination directory
14+
# ---------------------------------
15+
# If the destination directory exists, make sure that it's a Git checkout of the `gh-pages` branch.
16+
if [[ -d "$DST_DIR" ]]; then
17+
branch_name=$(cd "$DST_DIR" && git rev-parse --abbrev-ref HEAD)
18+
if [[ "$branch_name" != "$BRANCH_NAME" ]]; then
19+
echo "ERROR: Directory '$DST_DIR' is not a checkout of the '$BRANCH_NAME' branch!" 1>&2
20+
exit 1
21+
fi
22+
pwd=$(pwd)
23+
# Clean the Git checkout.
24+
echo "Git checkout found; cleaning"
25+
cd "$DST_DIR" && git clean -f
26+
cd "$pwd"
27+
# Otherwise, create it.
28+
else
29+
echo "No Git checkout found; cloning"
30+
mkdir -p $(dirname "$DST_DIR")
31+
git clone "$GIT_REPO_URL" -b "$BRANCH_NAME" --single-branch "$DST_DIR"
32+
fi
33+
34+
# Make the documentation
35+
# ----------------------
36+
# Clean the destination directory.
37+
echo "Cleaning destination directory"
38+
rm -rf "$DST_DIR"/*
39+
40+
# Online flavor -> root directory.
41+
echo "# Generating online flavor"
42+
"$PROJECT_ROOT/select-flavor.sh" online
43+
gradle javadoc
44+
# Offline flavor -> `offline` subdirectory.
45+
echo "# Generating offline flavor"
46+
"$PROJECT_ROOT/select-flavor.sh" offline
47+
gradle javadoc
48+
49+
# Copy license.
50+
LICENSE_FILE_NAME="LICENSE.txt"
51+
cp "$PROJECT_ROOT/LICENSE" "$DST_DIR/$LICENSE_FILE_NAME"
52+
cp "$PROJECT_ROOT/LICENSE" "$DST_DIR/offline/$LICENSE_FILE_NAME"
53+
54+
echo 'Done. Git diff then add and commit.'

0 commit comments

Comments
 (0)