Revise Schema Loader documentation #1196

josh-wong · 2023-10-17T06:29:28Z

Description

This PR revises the Schema Loader document.

Related issues and/or PRs

N/A

Changes made

Revised contents.
Added notice blocks for noteworthy content.
Added content tabs for databases.

The following is a screenshot of schema-loader.md on the docs site (locally).

Checklist

The following is a best-effort checklist. If any items in this checklist are not applicable to this PR or are dependent on other, unmerged PRs, please still mark the checkboxes after you have read and understood each item.

I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes.
Any remaining open issues linked to this PR are documented and up-to-date (Jira, GitHub, etc.).
Tests (unit, integration, etc.) have been added for the changes.
My changes generate no new warnings.
Any dependent changes in other PRs have been merged and published.

Additional notes (optional)

Please see the comments in the document.

Release notes

N/A

[skip ci]

josh-wong · 2023-10-17T06:34:42Z

docs/schema-loader.md

+<div id="tabset-1">
+<div class="tab">
+  <button class="tablinks" onclick="openTab(event, 'Install', 'tabset-1')" id="defaultOpen-1">Install</button>
+  <button class="tablinks" onclick="openTab(event, 'Build', 'tabset-1')">Build</button>
+  <button class="tablinks" onclick="openTab(event, 'Docker', 'tabset-1')">Docker</button>
+</div>
+
+<div id="Install" class="tabcontent" markdown="1">
+
+You can download the release versions of Schema Loader from the [ScalarDB Releases](https://github.com/scalar-labs/scalardb/releases) page.
+</div>
+<div id="Build" class="tabcontent" markdown="1">
+
+If you want to build Schema Loader from the source, run the following command:

-In case you want to build `schema-loader` from the source:
 ```console
 $ ./gradlew schema-loader:shadowJar
 ```
- The built fat jar file is `schema-loader/build/libs/scalardb-schema-loader-<version>.jar`

-## Docker
+Running that command builds a fat JAR file named `scalardb-schema-loader-<VERSION>.jar` in the `schema-loader/build/libs` folder, with `<VERSION>` matching the version of ScalarDB that you are using.
+</div>
+<div id="Docker" class="tabcontent" markdown="1">
+
+You can pull the Docker image from the [Scalar container registry](https://github.com/orgs/scalar-labs/packages/container/package/scalardb-schema-loader) by running the following command, replacing the contents in the angle brackets as described:

-You can pull the docker image from [Scalar's container registry](https://github.com/orgs/scalar-labs/packages/container/package/scalardb-schema-loader).
 ```console
-docker run --rm -v <your_local_schema_file_path>:<schema_file_path_in_docker> [-v <your_local_config_file_path>:<config_file_path_in_docker>] ghcr.io/scalar-labs/scalardb-schema-loader:<version> <command_arguments>
+docker run --rm -v <PATH_TO_YOUR_LOCAL_SCHEMA_FILE>:<PATH_TO_SCHEMA_FILE_DOCKER> [-v <PATH_TO_YOUR_LOCAL_PROPERTIES_FILE>:<PATH_TO_PROPERTIES_FILE_IN_DOCKER>] ghcr.io/scalar-labs/scalardb-schema-loader:<VERSION> <COMMAND_ARGUMENTS>
 ```
- Note that you can specify the same command arguments even if you use the fat jar or the container. The example commands in the next section are shown with a jar, but you can run the commands with the container in the same way by replacing `java -jar scalardb-schema-loader-<version>.jar` with `docker run --rm -v <your_local_schema_file_path>:<schema_file_path_in_docker> [-v <your_local_config_file_path>:<config_file_path_in_docker>] ghcr.io/scalar-labs/scalardb-schema-loader:<version>`.

-You can also build the docker image as follows.
+{% capture notice--info %}
+**Note**
+
+You can specify the same command arguments even if you use the fat JAR or the container. In the [Available commands](#available-commands) section, the JAR is used, but you can run the commands by using the container in the same way by replacing `java -jar scalardb-schema-loader-<VERSION>.jar` with `docker run --rm -v <PATH_TO_YOUR_LOCAL_SCHEMA_FILE>:<PATH_TO_SCHEMA_FILE_DOCKER> [-v <PATH_TO_YOUR_LOCAL_PROPERTIES_FILE>:<PATH_TO_PROPERTIES_FILE_IN_DOCKER>] ghcr.io/scalar-labs/scalardb-schema-loader:<VERSION>`.
+{% endcapture %}
+
+<div class="notice--info">{{ notice--info | markdownify }}</div>
+
+You can also build the Docker image as follows by running the following command:
+
 ```console
 $ ./gradlew schema-loader:docker
 ```
+</div>
+</div>


Note

This part within the <div> tags contains the three methods for setting up Schema Loader. On the docs site, these three methods will appear as tabbed content, allowing users to select their preferred setup method.

josh-wong · 2023-10-17T06:54:01Z

docs/schema-loader.md

+<div id="tabset-2">
+<div class="tab">
+  <button class="tablinks" onclick="openTab(event, 'Cassandra', 'tabset-2')" id="defaultOpen-2">Cassandra</button>
+  <button class="tablinks" onclick="openTab(event, 'Cosmos DB for NoSQL', 'tabset-2')">Cosmos DB for NoSQL</button>
+  <button class="tablinks" onclick="openTab(event, 'DynamoDB', 'tabset-2')">DynamoDB</button>
+  <button class="tablinks" onclick="openTab(event, 'JDBC_databases', 'tabset-2')">JDBC databases</button>
+</div>

-For Cassandra:
- `compaction-strategy`, a compaction strategy. It should be `STCS` (SizeTieredCompaction), `LCS` (LeveledCompactionStrategy) or `TWCS` (TimeWindowCompactionStrategy).
+<div id="Cassandra" class="tabcontent" markdown="1">

-For DynamoDB and Cosmos DB for NoSQL:
- `ru`, a request unit. Please see [RU](#ru) for the details.
+The `compaction-strategy` option is the compaction strategy used. This option should be `STCS` (SizeTieredCompaction), `LCS` (LeveledCompactionStrategy), or `TWCS` (TimeWindowCompactionStrategy).
+</div>
+<div id="Cosmos DB for NoSQL" class="tabcontent" markdown="1">

-## Scaling Performance
+The `ru` option stands for Request Units. For details, see [RUs](#rus).
+</div>
+<div id="DynamoDB" class="tabcontent" markdown="1">

-### RU
+The `ru` option stands for Request Units. For details, see [RUs](#rus).
+</div>
+<div id="JDBC_databases" class="tabcontent" markdown="1">

-You can scale the throughput of Cosmos DB for NoSQL and DynamoDB by specifying `--ru` option (which applies to all the tables) or `ru` parameter for each table. The default values are `400` for Cosmos DB for NoSQL and `10` for DynamoDB respectively, which are set without `--ru` option.
+No options are available for JDBC databases.
+</div>
+</div>


Note

This part within the <div> tags contains the options that users can specify for each database. On the docs site, these databases will appear as tabbed content, allowing users to select one of the databases.

docs/schema-loader.md

choplin

Overall, it looks good! I left several comments while approving the PR. PTAL!

docs/schema-loader.md

brfrn169

Left several comments. Please take a look when you have time!

docs/schema-loader.md

[skip ci]

feeblefakie

Overall, looking good! Thank you!
Left one comment, so PTAL!

docs/schema-loader.md

[skip ci]

komamitsu

LGTM! Thank you!

[skip ci]

brfrn169

Other than what I commented, LGTM! Thank you!

[skip ci] Remove a part about building the Docker image for Schema Loader.

[skip ci]

feeblefakie

LGTM! Thank you!

[skip ci] Remove mentions of features not available for this version of ScalarDB.

Revise doc

d9baa96

[skip ci]

josh-wong added the documentation label Oct 17, 2023

josh-wong self-assigned this Oct 17, 2023

josh-wong commented Oct 17, 2023

View reviewed changes

josh-wong marked this pull request as ready for review October 17, 2023 07:12

josh-wong requested review from komamitsu, brfrn169, choplin, feeblefakie and Torch3333 October 17, 2023 07:13

choplin approved these changes Oct 19, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

docs/schema-loader.md Show resolved Hide resolved

docs/schema-loader.md Outdated Show resolved Hide resolved

komamitsu reviewed Oct 20, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

docs/schema-loader.md Outdated Show resolved Hide resolved

brfrn169 approved these changes Oct 25, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

docs/schema-loader.md Show resolved Hide resolved

brfrn169 self-requested a review October 25, 2023 02:40

Apply suggestions from review

269c9ec

[skip ci]

feeblefakie reviewed Oct 30, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

Apply suggestions from review

aa16648

[skip ci]

josh-wong requested a review from komamitsu October 31, 2023 09:10

Put deprecated parts in a Note block and add tabs

f7ddc19

[skip ci]

komamitsu approved these changes Nov 2, 2023

View reviewed changes

Apply suggestions from review

1afb178

[skip ci]

brfrn169 approved these changes Nov 8, 2023

View reviewed changes

Remove part about building Docker image

ae73f08

[skip ci] Remove a part about building the Docker image for Schema Loader.

josh-wong requested a review from feeblefakie November 8, 2023 08:29

Clarify properties file in placeholder text

f302486

[skip ci]

feeblefakie approved these changes Nov 10, 2023

View reviewed changes

josh-wong added 2 commits November 10, 2023 18:37

Merge branch 'master' into revise-schema-loader-doc

b73d1b3

Merge branch 'master' into revise-schema-loader-doc

5e01d95

josh-wong merged commit 7e17ea7 into master Nov 13, 2023
23 checks passed

feeblefakie mentioned this pull request Nov 13, 2023

Backport to branch(3) : Revise Schema Loader documentation #1277

Merged

feeblefakie pushed a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

048702c

feeblefakie pushed a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

0f1f89e

feeblefakie mentioned this pull request Nov 13, 2023

Backport to branch(3.10) : Revise Schema Loader documentation #1278

Merged

feeblefakie pushed a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

928f987

josh-wong deleted the revise-schema-loader-doc branch November 13, 2023 04:32

josh-wong added a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

d9a55f3

[skip ci] Remove mentions of features not available for this version of ScalarDB.

josh-wong mentioned this pull request Nov 13, 2023

Backport to branch(3.8): Revise Schema Loader documentation #1283

Merged

josh-wong added a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

cb2a030

[skip ci] Remove mentions of features not available for this version of ScalarDB.

josh-wong mentioned this pull request Nov 13, 2023

Backport to branch(3.7): Revise Schema Loader documentation #1284

Merged

josh-wong added a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

19e5211

[skip ci] Remove mentions of features not available for this version of ScalarDB.

josh-wong added a commit that referenced this pull request Nov 13, 2023

Revise Schema Loader documentation (#1196)

cef6075

[skip ci] Remove mentions of features not available for this version of ScalarDB.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revise Schema Loader documentation #1196

Revise Schema Loader documentation #1196

josh-wong commented Oct 17, 2023 •

edited

Loading

josh-wong Oct 17, 2023

josh-wong Oct 17, 2023

choplin left a comment

brfrn169 left a comment

feeblefakie left a comment

komamitsu left a comment

brfrn169 left a comment

feeblefakie left a comment

Revise Schema Loader documentation #1196

Revise Schema Loader documentation #1196

Conversation

josh-wong commented Oct 17, 2023 • edited Loading

Description

Related issues and/or PRs

Changes made

Checklist

Additional notes (optional)

Release notes

josh-wong Oct 17, 2023

Choose a reason for hiding this comment

josh-wong Oct 17, 2023

Choose a reason for hiding this comment

choplin left a comment

Choose a reason for hiding this comment

brfrn169 left a comment

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

komamitsu left a comment

Choose a reason for hiding this comment

brfrn169 left a comment

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

josh-wong commented Oct 17, 2023 •

edited

Loading