[GraphQL/Docs][RFC] Move GraphQL References out from Sui API heading (M…

…ystenLabs#16019)

## Description

Create distinct top-level headings under "References" for "Sui JSON-RPC
API" and "Sui GraphQL API". This was to avoid a couple of confusing
aspects of the previous IA:

- It was unclear when reading "Sui API" what that was referring to
(GraphQL or JSON-RPC).
- The "RPC Best Practices" page (intended for JSON-RPC) was confusingly
next to the GraphQL references.

## Test Plan

```
docs/site$ pnpm build && pnpm start
```

+ 👀

.gitignore

@@ -70,4 +70,4 @@ yarn-error.log*
 .env
 checkpoints_dir/*
 light_client.yaml
-docs/content/references/sui-api/graphql/*
+docs/content/references/sui-graphql/*

crates/sui-graphql-rpc/src/main.rs

@@ -34,8 +34,8 @@ async fn main() {
         Command::GenerateDocsExamples => {
             let mut buf: PathBuf = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
             // we are looking to put examples content in
-            // sui/docs/content/references/sui-api/graphql/examples.mdx
-            let filename = "docs/content/references/sui-api/graphql/examples.mdx";
+            // sui/docs/content/references/sui-graphql/examples.mdx
+            let filename = "docs/content/references/sui-graphql/examples.mdx";
             buf.pop();
             buf.pop();
             buf.push(filename);

docs/content/guides/developer/advanced/graphql-migration.mdx

@@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
 
 This guide compares JSON-RPC queries to their equivalent GraphQL counterpart. While it is possible to systematically rewrite JSON-RPC queries (for example, `sui_getTotalTransactionBlocks`) to their GraphQL counterparts using this guide, it is recommended that you revisit your application's query patterns to take full advantage of the flexibility that GraphQL offers in serving queries that touch multiple potentially nested endpoints (for example transactions, balances, coins), and use the following examples to get a flavor of how the two APIs express similar concepts.
 
-For a comprehensive list of all available GraphQL APIs, consult the [reference](../../../references/sui-api/graphql).
+For a comprehensive list of all available GraphQL APIs, consult the [reference](../../../references/sui-graphql).
 
 ### Example 1: Get total transaction blocks
 

docs/content/guides/developer/getting-started/graphql-rpc.mdx

@@ -14,7 +14,7 @@ The online IDE is available for [mainnet](https://sui-mainnet.mystenlabs.com/gra
 - Both [mainnet](https://sui-mainnet.mystenlabs.com/graphql) and [testnet](https://sui-testnet.mystenlabs.com/graphql) services are rate-limited to keep network throughput optimized.
 :::
 
-For more details about some concepts used in the examples below, please see the [GraphQL concepts](concepts/graphql-rpc.mdx) page, and consult the [reference](../../../references/sui-api/graphql) for full documentation on the supported schema.
+For more details about some concepts used in the examples below, please see the [GraphQL concepts](concepts/graphql-rpc.mdx) page, and consult the [reference](../../../references/sui-graphql) for full documentation on the supported schema.
 
 
 ## Discovering the schema

docs/content/references.mdx

@@ -15,7 +15,7 @@ Reference the Sui framework documentation to understand the Move code that power
 <Card title="Sui Framework" href="https://github.com/MystenLabs/sui/tree/main/crates/sui-framework/docs">
 Sui framework reference for the Move packages that power the blockchain.
 </Card>
-<Card title="GraphQL RPC" href="references/sui-api/graphql"/>
+<Card title="GraphQL RPC" href="references/sui-graphql"/>
 <Card title="Sui API reference" href="references/sui-api">
 API reference for the SUI API in JSON RPC format.
 </Card>

docs/content/references/sui-api/graphql.mdx → docs/content/references/sui-graphql.mdx

@@ -1,6 +1,6 @@
 ---
-title: Sui GraphQL RPC Overview
-description: The Sui GraphQL RPC is a public service that enables interacting with the Sui network. 
+title: Sui GraphQL API
+description: The Sui GraphQL RPC is a public service that enables interacting with the Sui network.
 ---
 
 The Sui GraphQL RPC is a public service that enables interacting with the Sui [network](https://sui.io/networkinfo).
@@ -9,4 +9,4 @@ To get started with the GraphQL RPC, check out the [Getting Started](/guides/dev
 
 Check out the `Queries` reference page on the left sidebar for the root types related to querying the service (e.g., doing a `dryRun`). If you'd like to execute a transaction on the network, check out the `Mutations` page in the left sidebar.
 
-As Sui uses an object-centric model, it might be of interest to explore the [Object](/references/sui-api/graphql/reference/objects/object.mdx) and [Address](/references/sui-api/graphql/reference/objects/address.mdx) types too. For other types and reference API, consult the pages under GraphQL RPC API shown in the left sidebar.
+As Sui uses an object-centric model, it might be of interest to explore the [Object](/references/sui-graphql/reference/objects/object.mdx) and [Address](/references/sui-graphql/reference/objects/address.mdx) types too. For other types and reference API, consult the pages under GraphQL RPC API shown in the left sidebar.

docs/content/sidebars/references.js

@@ -14,26 +14,12 @@ const references = [
 	},
 	{
 		type: 'category',
-		label: 'Sui API',
+		label: 'Sui JSON-RPC API',
 		link: {
 			type: 'doc',
 			id: 'references/sui-api',
 		},
 		items: [
-			{
-				type: 'category',
-				label: 'GraphQL RPC API',
-				link: {
-					type: 'doc',
-					id: 'references/sui-api/graphql'
-				},
-				items: [
-					{
-						type: 'autogenerated',
-						dirName: 'references/sui-api/graphql/reference',
-					},
-				],
-			},
 			{
 				type: 'link',
 				label: 'API Reference',
@@ -42,6 +28,20 @@ const references = [
 			'references/sui-api/rpc-best-practices',
 		],
 	},
+	{
+		type: 'category',
+		label: 'Sui GraphQL API',
+		link: {
+			type: 'doc',
+			id: 'references/sui-graphql',
+		},
+		items: [
+			{
+				type: 'autogenerated',
+				dirName: 'references/sui-graphql/reference',
+			},
+		],
+	},
 	{
 		type: 'category',
 		label: 'Sui CLI',

docs/site/docusaurus.config.js

@@ -44,7 +44,7 @@ const config = {
         schema:
           "../../crates/sui-graphql-rpc/schema/current_progress_schema.graphql",
         rootPath: "../content", // docs will be generated under rootPath/baseURL
-        baseURL: "references/sui-api/graphql/reference",
+        baseURL: "references/sui-graphql/reference",
         loaders: {
           GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
         },