Enhance documentations

paion-data · Aug 14, 2024 · fb4a724 · fb4a724
1 parent e3fcd3d
commit fb4a724
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 112 deletions.
diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md
@@ -3,20 +3,6 @@ sidebar_position: 4
 title: Configuration
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 The configurations in this page can be set from several sources in the following order:
 
 1. the [operating system's environment variables]; for instance, an environment variable can be set with

diff --git a/docs/docs/development.md b/docs/docs/development.md
@@ -3,20 +3,6 @@ sidebar_position: 3
 title: Development
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 Running Tests
 -------
 

diff --git a/docs/docs/img/graphiql.png b/docs/docs/img/graphiql.png
diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx
@@ -3,20 +3,6 @@ sidebar_position: 1
 title: Getting Started
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -62,6 +48,8 @@ mvn clean package --settings settings.xml.example
 MODEL_PACKAGE_NAME=com.paiondata.astraios.data.models docker compose up --build --force-recreate
 ```
 
+Note that the `settings.xml` is the [Maven config file for loading the data model](#loading-data-models)
+
 :::info
 
 - `com.paiondata.astraios.data.models` is the name of the model in the aforementioned
@@ -71,9 +59,47 @@ MODEL_PACKAGE_NAME=com.paiondata.astraios.data.models docker compose up --build
 
 :::
 
+If everything runs successfully, we should be able to see the following output at end of the command line output:
+
+```console
+web-1  | 25-06-2024 04:41:53.654 [main] [Elide, ] INFO  o.a.coyote.http11.Http11NioProtocol.log - Starting ProtocolHandler ["http-nio-8080"]
+web-1  | 25-06-2024 04:41:53.676 [main] [Elide, ] INFO  o.s.b.w.e.tomcat.TomcatWebServer.start - Tomcat started on port(s): 8080 (http) with context path ''
+web-1  | 25-06-2024 04:41:53.709 [main] [Elide, ] INFO  com.paiondata.astraios.App.logStarted - Started App in 14.755 seconds (process running for 16.004)
+```
+
+A MySQL database container has also started alongside and is accessible via
+
+```console
+mysql -h localhost -D elide -P 3306 --protocol=tcp -u root -proot
+```
+
+All data is persisted in a database called __elide__
+
 Writing Data
 ------------
 
+:::tip[Installing GraphiQL]
+
+GraphiQL offers a user-friendly UI for issuing GraphQL queries and displaying query responses. We can use it for the
+API call below.
+
+- __Mac__ uses [Homebrew](https://formulae.brew.sh/cask/graphiql)
+
+  ```console
+  brew install --cask graphiql
+  ```
+
+- __Windows__ binary can be downloaded from the [release page](https://github.com/skevy/graphiql-app/releases).
+  Then install the downloaded `.exe` file
+- __Linux__ users can follow the
+  [official documentation](https://github.com/skevy/graphiql-app?tab=readme-ov-file#linux-installation)
+
+When installed, the GraphiQL user interface looks like the following:
+
+![Error loading graphiql.png](./img/graphiql.png)
+
+:::
+
 ### Inserting Data
 
 We have defined our views on the database and exposed those views over HTTP. Next let's use cURL to put data in the

diff --git a/docs/docs/setup.md b/docs/docs/setup.md
@@ -3,20 +3,6 @@ sidebar_position: 2
 title: Setup
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 This section discusses the one-time setup in order to develop [Astraios].
 
 Prepare for Local Development

diff --git a/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/configuration.md b/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/configuration.md
@@ -3,20 +3,6 @@ sidebar_position: 4
 title: 配置
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 此页面中的配置可以按照以下顺序从以下几个来源进行设置，：
 
 1. [操作系统的环境变量]；例如，可以通过 `export DB_URL="jdbc:mysql://db/elide?serverTimezone=UTC"` 设置环境变量

diff --git a/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/development.md b/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/development.md
@@ -3,20 +3,6 @@ sidebar_position: 3
 title: 开发
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 运行测试
 -------
 

diff --git a/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/intro.mdx b/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/intro.mdx
@@ -3,20 +3,6 @@ sidebar_position: 1
 title: 快速入门
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

diff --git a/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/setup.md b/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/setup.md
@@ -3,20 +3,6 @@ sidebar_position: 2
 title: 设置
 ---
 
-[//]: # (Copyright 2024 Paion Data)
-
-[//]: # (Licensed under the Apache License, Version 2.0 &#40;the "License"&#41;;)
-[//]: # (you may not use this file except in compliance with the License.)
-[//]: # (You may obtain a copy of the License at)
-
-[//]: # (    http://www.apache.org/licenses/LICENSE-2.0)
-
-[//]: # (Unless required by applicable law or agreed to in writing, software)
-[//]: # (distributed under the License is distributed on an "AS IS" BASIS,)
-[//]: # (WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.)
-[//]: # (See the License for the specific language governing permissions and)
-[//]: # (limitations under the License.)
-
 本节讨论开发 [Astraios] 的一次性设置。
 
 为本地开发做好准备