refactor(interactive): Refine the documentation of Interactive SDK (#…

…4268) The current Interactive SDK documentation only includes the Service APIs and code generated by openapi-generator. This PR adds auto-generated documentation for the hand-written wrapper and utility classes for SDKs. Also add comments to python/java sdk code. Fix #4263
alibaba · Sep 29, 2024 · 1b4b809 · 1b4b809
1 parent 47dbed3
commit 1b4b809
Show file tree

Hide file tree

Showing 38 changed files with 562 additions and 132 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -36,6 +36,11 @@ clean:
 	@echo "Tag is:" $(TAG)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)/$(TAG)" $(SPHINXOPTS) $(O)
 
+	@echo "Building Interactive Java SDK doc"
+
+	cd ${WORKING_DIR}/../flex/interactive/sdk/java && \
+	mvn javadoc::javadoc -Djavadoc.output.directory=${WORKING_DIR}/$(BUILDDIR)/${TAG}/$@/flex/interactive/development/java/ -Djavadoc.output.destDir=reference
+
 	@echo "Building Java doc to $(BUILDDIR)/${TAG}/$@/reference/gae_java"
 
 	cd ${WORKING_DIR}/../analytical_engine/java && \
@@ -60,6 +65,8 @@ interactive-sdk:
 	@cd ${WORKING_DIR}/../flex/interactive/sdk/ && ./generate_sdk.sh -g java \
 		&& ./generate_sdk.sh -g python
 
+	@cd ${WORKING_DIR}/../flex/interactive/sdk/python && pip3 install -r requirements.txt && python3 setup.py build_proto && pip3 install .
+
 	@cd ${WORKING_DIR}/../flex/interactive/sdk/ && bash generate_sdk_doc.sh -o ${WORKING_DIR}/flex/interactive/development/
 
 coordinator-sdk-doc:

diff --git a/docs/flex/interactive/development/java/EdgeApi.md b/docs/flex/interactive/development/java/EdgeApi.md
@@ -1,4 +1,5 @@
-# EdgeAPi
+[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst
+# EdgeAPI
 
 All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
 
@@ -12,7 +13,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
 
 <a id="addEdge"></a>
 # **addEdge**
-> Result&lt;String&gt; addEdge(graphId, edgeRequest)
+> [Result][Result-doc]&lt;String&gt; addEdge(graphId, edgeRequest)
 
 Add edge to the graph. 
 
@@ -72,7 +73,7 @@ public class Example {
 
 ### Return type
 
-**String**
+[Result][Result-doc]&lt;**String**&gt;
 
 ### Authorization
 
@@ -93,7 +94,7 @@ No authorization required
 
 <a id="getEdge"></a>
 # **getEdge**
-> Result&lt;EdgeData&gt; getEdge(graphId, edgeLabel, srcLabel, srcPrimaryKeyValue, dstLabel, dstPrimaryKeyValue)
+> [Result][Result-doc]&lt;EdgeData&gt; getEdge(graphId, edgeLabel, srcLabel, srcPrimaryKeyValue, dstLabel, dstPrimaryKeyValue)
 
 Get the edge&#39;s properties with src and dst vertex primary keys.
 
@@ -162,7 +163,7 @@ No authorization required
 
 <a id="updateEdge"></a>
 # **updateEdge**
-> Result&lt;String&gt; updateEdge(graphId, edgeRequest)
+> [Result][Result-doc]&lt;String&gt; updateEdge(graphId, edgeRequest)
 
 Update edge&#39;s property
 
@@ -209,7 +210,7 @@ public class Example {
 
 ### Return type
 
-**String**
+[Result][Result-doc]&lt;**String**&gt;
 
 ### Authorization
 

diff --git a/docs/flex/interactive/development/java/GraphManagementApi.md b/docs/flex/interactive/development/java/GraphManagementApi.md
@@ -1,3 +1,5 @@
+[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst
+
 # GraphManagementApi
 
 All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
@@ -15,7 +17,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
 
 <a id="ListGraphs"></a>
 # **ListGraphs**
-> Result&lt;List&lt;GetGraphResponse&gt;&gt; getAllGraphs()
+> [Result][Result-doc]&lt;List&lt;GetGraphResponse&gt;&gt; getAllGraphs()
 
 
 
@@ -51,7 +53,7 @@ None.
 
 ### Return type
 
-[**Result&lt;List&lt;GetGraphResponse&gt;&gt;**](GetGraphResponse.md)
+[Result][Result-doc]&lt;List&lt;[GetGraphResponse](GetGraphResponse.md)&gt;&gt;
 
 ### Authorization
 
@@ -70,7 +72,7 @@ No authorization required
 
 <a id="CreateGraph"></a>
 # **CreateGraph**
-> Result&lt;CreateGraphResponse&gt; createGraph(createGraphRequest)
+> [Result][Result-doc]&lt;CreateGraphResponse&gt; createGraph(createGraphRequest)
 
 
 
@@ -159,7 +161,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;CreateGraphResponse&gt;**](CreateGraphResponse.md)
+[Result][Result-doc]&lt;[CreateGraphResponse](CreateGraphResponse.md)&gt;
 
 ### Authorization
 
@@ -180,7 +182,7 @@ No authorization required
 
 <a id="BulkLoading"></a>
 # **BulkLoading**
-> Result&lt;JobResponse&gt; bulkLoading(graphId, schemaMapping)
+> [Result][Result-doc]&lt;JobResponse&gt; bulkLoading(graphId, schemaMapping)
 
 
 
@@ -313,7 +315,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;JobResponse&gt;**](JobResponse.md)
+[Result][Result-doc]&lt;[JobResponse](JobResponse.md)&gt;
 
 ### Authorization
 
@@ -331,7 +333,7 @@ No authorization required
 
 <a id="DeleteGraph"></a>
 # **DeleteGraph**
-> Result&lt;String&gt; deleteGraph(graphId)
+> [Result][Result-doc]&lt;String&gt; deleteGraph(graphId)
 
 
 
@@ -370,7 +372,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;String&gt;**
+[Result][Result-doc]&lt;String&gt;
 
 ### Authorization
 
@@ -390,7 +392,7 @@ No authorization required
 
 <a id="GetGraphMeta"></a>
 # **GetGraphMeta**
-> Result&lt;GetGraphResponse&gt; getGraphMeta(graphId)
+> [Result][Result-doc]&lt;GetGraphResponse&gt; getGraphMeta(graphId)
 
 
 
@@ -428,7 +430,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;GetGraphResponse&gt;**](GetGraphResponse.md)
+[Result][Result-doc]&lt;[GetGraphResponse](GetGraphResponse.md)&gt;
 
 ### Authorization
 
@@ -542,7 +544,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;GetGraphSchemaResponse&gt;**](GetGraphSchemaResponse.md)
+[Result][Result-doc]&lt;[GetGraphSchemaResponse](GetGraphSchemaResponse.md)&gt;
 
 ### Authorization
 

diff --git a/docs/flex/interactive/development/java/JobManagementApi.md b/docs/flex/interactive/development/java/JobManagementApi.md
@@ -1,3 +1,5 @@
+[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst
+
 # JobManagementApi
 
 All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
@@ -11,7 +13,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
 
 <a id="CancelJob"></a>
 # **CancelJob**
-> Result&lt;String&gt; cancelJob(jobId)
+> [Result][Result-doc]&lt;String&gt; cancelJob(jobId)
 
 See [bulkLoading](GraphManagementApi.md#bulkloading) about how to submit a bulk loading job.
 
@@ -47,7 +49,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;String&gt;**
+[Result][Result-doc]&lt;String&gt;
 
 ### Authorization
 
@@ -65,7 +67,7 @@ No authorization required
 
 <a id="GetJobById"></a>
 # **GetJobById**
-> Result&lt;JobStatus&gt; getJobById(jobId)
+> [Result][Result-doc]&lt;JobStatus&gt; getJobById(jobId)
 
 
 
@@ -100,7 +102,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;JobStatus&gt;**](JobStatus.md)
+[Result][Result-doc]&lt;[JobStatus](JobStatus.md)&gt;
 
 ### Authorization
 
@@ -149,7 +151,7 @@ This endpoint does not need any parameter.
 
 ### Return type
 
-[**Result&lt;List&lt;JobStatus&gt;&gt;**](JobStatus.md)
+[Result][Result-doc]&lt;List&lt;[JobStatus](JobStatus.md)&gt;&gt;
 
 ### Authorization
 

diff --git a/docs/flex/interactive/development/java/ProcedureManagementApi.md b/docs/flex/interactive/development/java/ProcedureManagementApi.md
@@ -1,3 +1,5 @@
+[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst
+
 # ProcedureManagementApi
 
 All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
@@ -13,7 +15,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
 
 <a id="CreateProcedure"></a>
 # **CreateProcedure**
-> Result&lt;CreateProcedureResponse&gt; createProcedure(graphId, createProcedureRequest)
+> [Result][Result-doc]&lt;CreateProcedureResponse&gt; createProcedure(graphId, createProcedureRequest)
 
 
 Create a new procedure on a graph with give id. 
@@ -60,7 +62,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;CreateProcedureResponse&gt;**](CreateProcedureResponse.md)
+[Result][Result-doc]&lt;[CreateProcedureResponse](CreateProcedureResponse.md)&gt;
 
 ### Authorization
 
@@ -81,7 +83,7 @@ No authorization required
 
 <a id="DeleteProcedure"></a>
 # **DeleteProcedure**
-> Result&lt;String&gt; deleteProcedure(graphId, procedureId)
+> [Result][Result-doc]&lt;String&gt; deleteProcedure(graphId, procedureId)
 
 
 
@@ -120,7 +122,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;String&gt;**
+[Result][Result-doc]&lt;String&gt;
 
 ### Authorization
 
@@ -178,7 +180,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;GetProcedureResponse&gt;**](GetProcedureResponse.md)
+[Result][Result-doc]&lt;[GetProcedureResponse](GetProcedureResponse.md)&gt;
 
 ### Authorization
 
@@ -197,7 +199,7 @@ No authorization required
 
 <a id="ListProcedures"></a>
 # **ListProcedures**
-> Result&lt;List&lt;GetProcedureResponse&gt;&gt; listProcedures(graphId)
+> [Result][Result-doc]&lt;List&lt;GetProcedureResponse&gt;&gt; listProcedures(graphId)
 
 
 
@@ -237,7 +239,7 @@ public class Example {
 
 ### Return type
 
-[**Result&lt;List&lt;GetProcedureResponse&gt;&gt;**](GetProcedureResponse.md)
+[Result][Result-doc]]&lt;List&lt;[GetProcedureResponse](GetProcedureResponse.md)&gt;&gt;
 
 ### Authorization
 
@@ -301,7 +303,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;String&gt;**
+[Result][Result-doc]&lt;String&gt;
 
 ### Authorization
 

diff --git a/docs/flex/interactive/development/java/QueryServiceApi.md b/docs/flex/interactive/development/java/QueryServiceApi.md
@@ -1,3 +1,5 @@
+[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst
+
 # QueryServiceApi
 
 All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}*
@@ -14,7 +16,7 @@ If you attempt to submit a query to a graph that is not currently running, we wi
 
 <a id="CallProcedure"></a>
 # **CallProcedure**
-> Result&lt;IrResult.CollectiveResults&gt; callProcedure(graphId, request)
+> [Result][Result-doc]&lt;IrResult.CollectiveResults&gt; callProcedure(graphId, request)
 
 Submit procedure call queries to the specified graph.
 The output format for the query is define by the [results.proto](https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/ir/proto/results.proto).
@@ -69,7 +71,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;IrResult.CollectiveResults&gt;**
+[Result][Result-doc]&lt;IrResult.CollectiveResults&gt;
 
 ### Authorization
 
@@ -88,7 +90,7 @@ No authorization required
 
 <a id="CallProcedureOnCurrentGraph"></a>
 # **CallProcedureOnCurrentGraph**
-> Result&lt;IrResult.CollectiveResults&gt; callProcedure(body)
+> [Result][Result-doc]&lt;IrResult.CollectiveResults&gt; callProcedure(body)
 
 Submit a query to the running graph. 
 
@@ -139,7 +141,7 @@ public class Example {
 
 ### Return type
 
-**Result&lt;IrResult.CollectiveResults&gt;**
+[Result][Result-doc]&lt;IrResult.CollectiveResults&gt;
 
 ### Authorization