Skip to content

Commit 66fcae1

Browse files
ForteScarletForteScarlet
committed
docs: improve documentation structure and styling
- Replaced Markdown notes with Docusaurus `:::note` syntax for better readability - Updated primary color palette in CSS for a refreshed look - Added gradients in styles for a visually enhanced experience - Included `dayjs` dependency in `package.json` for better date handling
1 parent 7ccbd1e commit 66fcae1

File tree

22 files changed

+259
-92
lines changed

22 files changed

+259
-92
lines changed

‎docs/docs/configuration/configuration.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,11 @@ suspendTransformPlugin {
105105
}
106106
```
107107

108-
> `love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations`
109-
> contains some information about the standard implementations we provide.
108+
:::info
109+
`love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations`
110+
contains some information about the standard implementations we provide.
111+
:::
112+
110113

111114
### Using Default Transformers
112115

@@ -116,8 +119,11 @@ You can use them simply and quickly through configuration.
116119
For information on using the default transformers,
117120
refer to [Default Transformers](default-transformers.md).
118121

119-
> **Note**: The default `Transformer`s depend on the `annotation` and `runtime` we provide.
120-
> Make sure you include them before using it.
122+
:::note
123+
The default `Transformer`s depend on the `annotation` and `runtime` we provide.
124+
Make sure you include them before using it.
125+
:::
126+
121127

122128
## Complete Configuration Example
123129

‎docs/docs/configuration/custom-transformers.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,11 @@ This guide covers how to create custom transformers when the default transformer
1313
You can create fully customized transformers if the default ones don't meet your requirements.
1414
For example, if you want to implement blocking logic without using `kotlinx.coroutines.runBlocking`, or if you need platform-specific behavior.
1515

16-
> Reference Implementation: A fully customized implementation of JVM Blocking/Async Transformers can be found at:
17-
> [simbot's BlockingRunner](https://github.com/simple-robot/simpler-robot/blob/v4-main/simbot-commons/simbot-common-suspend-runner/src/jvmMain/kotlin/love/forte/simbot/suspendrunner/BlockingRunner.kt)
16+
:::info
17+
A fully customized implementation of JVM Blocking/Async Transformers can be found at:
18+
[simbot's BlockingRunner](https://github.com/simple-robot/simpler-robot/blob/v4-main/simbot-commons/simbot-common-suspend-runner/src/jvmMain/kotlin/love/forte/simbot/suspendrunner/BlockingRunner.kt)
19+
:::
20+
1821

1922
:::warning Known Issue
2023
Custom transformer functions cannot be placed in the same module as the one using the compiler plugin. They need to

‎docs/docs/configuration/default-transformers.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,11 @@ This guide covers the default transformers provided by the plugin and how to use
1414
Transformers are the core components that define how suspend functions are transformed for different platforms.
1515
The plugin provides several built-in transformers that cover the most common use cases.
1616

17-
> **Note**: The default transformers depend on the `annotation` and `runtime` dependencies provided by the plugin.
18-
> Make sure you include them in your configuration before using default transformers.
17+
:::note
18+
The default transformers depend on the `annotation` and `runtime` dependencies provided by the plugin.
19+
Make sure you include them in your configuration before using default transformers.
20+
:::
21+
1922

2023
## JVM Transformers
2124

@@ -114,7 +117,10 @@ val fooBlocking: T
114117
get() = runInBlocking { foo() }
115118
```
116119

117-
> **Note**: If `asProperty` is `true`, the function cannot have parameters.
120+
:::note
121+
If `asProperty` is `true`, the function cannot have parameters.
122+
:::
123+
118124

119125
##### markName {#jvmblocking-markname}
120126

@@ -220,7 +226,10 @@ val fooAsync: CompletableFuture<out T>
220226
get() = runInAsync { foo() }
221227
```
222228

223-
> **Note**: If `asProperty` is `true`, the function cannot have parameters.
229+
:::note
230+
If `asProperty` is `true`, the function cannot have parameters.
231+
:::
232+
224233

225234
##### markName {#jvmasync-markname}
226235

@@ -326,7 +335,10 @@ val fooAsync: Promise<T>
326335
get() = runInAsync { foo() }
327336
```
328337

329-
> **Note**: If `asProperty` is `true`, the function cannot have parameters.
338+
:::note
339+
If `asProperty` is `true`, the function cannot have parameters.
340+
:::
341+
330342

331343
##### markName {#jspromise-markname}
332344

‎docs/docs/features/mark-name.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,11 @@ class Foo {
9595

9696
In custom annotations, you can configure `markName`.
9797

98-
> For basic information about custom annotations (and transformers),
99-
> refer to [Custom Transformers](../configuration/custom-transformers.md).
98+
:::info
99+
For basic information about custom annotations (and transformers),
100+
refer to [Custom Transformers](../configuration/custom-transformers.md).
101+
:::
102+
100103

101104
:::warning
102105
TODO

‎docs/docs/getting-started.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,10 @@ class Foo {
118118
</TabItem>
119119
</Tabs>
120120

121-
> **Note**: JS platform support was added in version 0.6.0! See the development process at [KT-53993](https://youtrack.jetbrains.com/issue/KT-53993), and the final implementation at [#39](https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/pull/39)!
121+
:::note
122+
JS platform support was added in version 0.6.0! See the development process at [KT-53993](https://youtrack.jetbrains.com/issue/KT-53993), and the final implementation at [#39](https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/pull/39)!
123+
:::
124+
122125

123126
## WasmJS Platform
124127

‎docs/docs/installation.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,12 @@ If the version is less than or equal to `0.9.0`, you can refer to this compariso
3636
| `1.9.0` | `0.5.0` |
3737
| `1.8.21` | `0.3.1` ~ `0.4.0` |
3838

39-
> **Note**: I haven't documented in detail the compiler plugin compatibility between each Kotlin version.
40-
> From my memory and guess, Kotlin versions have a higher probability of incompatibility when minor is added (e.g. `1.8.0` -> `1.9.0`),
41-
> and a smaller probability of incompatibility when patch is added (e.g. `1.9.21` -> `1.9.22`).
39+
:::note
40+
I haven't documented in detail the compiler plugin compatibility between each Kotlin version.
41+
From my memory and guess, Kotlin versions have a higher probability of incompatibility when minor is added (e.g. `1.8.0` -> `1.9.0`),
42+
and a smaller probability of incompatibility when patch is added (e.g. `1.9.21` -> `1.9.22`).
43+
:::
44+
4245

4346
## Gradle Setup
4447

‎docs/docs/overview.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,9 @@ class Foo {
8383
| JavaScript | 0.6.0 |
8484
| WasmJS (Experimental) | 0.6.0 |
8585

86-
> **Note**: JS platform support was added in version 0.6.0. See the implementation details
87-
> at [KT-53993](https://youtrack.jetbrains.com/issue/KT-53993)
88-
> and [PR #39](https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/pull/39).
86+
:::note
87+
JS platform support was added in version 0.6.0. See the implementation details
88+
at [KT-53993](https://youtrack.jetbrains.com/issue/KT-53993)
89+
and [PR #39](https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/pull/39).
90+
:::
91+

‎docs/docs/possibly-useful/examples.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -464,7 +464,10 @@ class OrderService : CoroutineScope {
464464

465465
**Compiled Result:**
466466

467-
> _Simplified from decompiled results._
467+
:::tip
468+
_Simplified from decompiled results._
469+
:::
470+
468471

469472
```kotlin
470473
import love.forte.plugin.suspendtrans.annotation.*

‎docs/docusaurus.config.ts‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,14 @@ const config: Config = {
6363
sidebarPath: './sidebars.ts',
6464
// Please change this to your repo.
6565
// Remove this to remove the "edit this page" links.
66-
editUrl: ({locale, docPath}) => {
67-
if (locale === 'zh-CN') {
68-
return `https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/tree/dev/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/${docPath}`;
69-
}
70-
return `https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/tree/dev/docs/${docPath}`;
71-
},
66+
// editUrl: ({locale, docPath}) => {
67+
// if (locale === 'zh-CN') {
68+
// return `https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/tree/dev/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/${docPath}`;
69+
// }
70+
// return `https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/tree/dev/docs/${docPath}`;
71+
// },
72+
editUrl: 'https://github.com/ForteScarlet/kotlin-suspend-transform-compiler-plugin/tree/dev/docs/',
73+
editLocalizedFiles: true,
7274
showLastUpdateTime: true,
7375
lastVersion: 'current',
7476
versions: {

‎docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/configuration/configuration.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,8 +104,11 @@ suspendTransformPlugin {
104104
}
105105
```
106106

107-
> `love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations`
108-
> 包含一些我们提供的标准实现的信息。
107+
:::info
108+
`love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations`
109+
包含一些我们提供的标准实现的信息。
110+
:::
111+
109112

110113
### 使用默认转换器
111114

@@ -115,8 +118,11 @@ suspendTransformPlugin {
115118
有关使用默认转换器的信息，
116119
请参考 [默认转换器](./default-transformers.md)。
117120

118-
> **注意**：默认的 `Transformer` 依赖于我们提供的 `annotation` 和 `runtime`。
119-
> 在使用之前请确保您包含了它们。
121+
:::note
122+
默认的 `Transformer` 依赖于我们提供的 `annotation` 和 `runtime`。
123+
在使用之前请确保您包含了它们。
124+
:::
125+
120126

121127
## 完整配置示例
122128

0 commit comments

Comments
 (0)