Skip to content

Commit 67f6b93

Browse files
ForteScarletForteScarlet
authored
Merge pull request #103 from ForteScarlet/doc
doc: documentation site
2 parents 8c0ee19 + 6390cb6 commit 67f6b93

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+4635
-0
lines changed

‎.github/workflows/doc-publish.yml‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
name: Deploy documentation
2+
3+
on:
4+
# If specified, the workflow will be triggered automatically once you push to the `main` branch.
5+
# Replace `main` with your branch’s name
6+
push:
7+
branches:
8+
- dev
9+
paths:
10+
- 'docs/**'
11+
- 'docs_zh/**'
12+
- 'docs_en/**'
13+
- '.github/workflows/doc-publish.yml'
14+
15+
# Specify to run a workflow manually from the Actions tab on GitHub
16+
workflow_dispatch:
17+
18+
# Gives the workflow permissions to clone the repo and create a page deployment
19+
permissions:
20+
id-token: write
21+
pages: write
22+
23+
env:
24+
# Name of module and id separated by a slash
25+
INSTANCE: docs/docs
26+
INSTANCE_NAME: docs
27+
IS_GROUP: true
28+
# Replace HI with the ID of the instance in capital letters
29+
ARTIFACT: webHelpDOCS2-all.zip
30+
# Writerside docker image version
31+
# see https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html
32+
DOCKER_VERSION: '2025.04.8412'
33+
34+
jobs:
35+
build:
36+
runs-on: ubuntu-latest
37+
outputs:
38+
config_json: ${{ steps.output-config-json.outputs.config_json }}
39+
40+
steps:
41+
- name: Checkout repository
42+
uses: actions/checkout@v4
43+
44+
- name: Build Writerside docs using Docker
45+
uses: JetBrains/writerside-github-action@v4
46+
with:
47+
instance: ${{ env.INSTANCE }}
48+
artifact: ${{ env.ARTIFACT }}
49+
docker-version: ${{ env.DOCKER_VERSION }}
50+
is-group: ${{ env.IS_GROUP }}
51+
52+
- name: Upload documentation
53+
uses: actions/upload-artifact@v4
54+
with:
55+
name: docs
56+
path: |
57+
artifacts/${{ env.ARTIFACT }}
58+
artifacts/report.json
59+
retention-days: 7
60+
61+
- name: Upload documentation test reports
62+
uses: actions/upload-artifact@v4
63+
if: ${{ always() }}
64+
with:
65+
name: 'report.json'
66+
path: |
67+
artifacts/report.json
68+
retention-days: 7
69+
70+
- name: Unzip artifact
71+
run: unzip -O UTF-8 -qq artifacts/${{ env.ARTIFACT }} -d dir
72+
73+
- name: Output documentation config.json
74+
id: output-config-json
75+
run: |
76+
echo "config_json=$(cat dir/config.json)" >> $GITHUB_OUTPUT
77+
78+
# Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors
79+
test:
80+
# Requires build job results
81+
needs: build
82+
runs-on: ubuntu-latest
83+
84+
steps:
85+
- name: Download artifacts
86+
uses: actions/download-artifact@v4
87+
with:
88+
name: docs
89+
path: artifacts
90+
91+
- name: Test documentation
92+
uses: JetBrains/writerside-checker-action@v1
93+
with:
94+
instance: ${{ env.INSTANCE }}
95+
is-group: ${{ env.IS_GROUP }}
96+
97+
deploy:
98+
environment:
99+
name: github-pages
100+
url: ${{ steps.deployment.outputs.page_url }}
101+
# Requires the build job results
102+
needs: test
103+
runs-on: ubuntu-latest
104+
steps:
105+
- name: Download artifact
106+
uses: actions/download-artifact@v4
107+
with:
108+
name: docs
109+
110+
- name: Unzip artifact
111+
run: unzip -O UTF-8 -qq artifacts/${{ env.ARTIFACT }} -d dir
112+
113+
- name: Setup Pages
114+
uses: actions/configure-pages@v5
115+
116+
- name: Upload artifact
117+
uses: actions/upload-pages-artifact@v3
118+
with:
119+
path: dir
120+
121+
- name: Deploy to GitHub Pages
122+
id: deployment
123+
uses: actions/deploy-pages@v4

‎.github/workflows/doc-test.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Test documentation
2+
3+
on:
4+
# If specified, the workflow will be triggered automatically once you push to the `main` branch.
5+
# Replace `main` with your branch’s name
6+
pull_request:
7+
branches:
8+
- dev
9+
# Specify to run a workflow manually from the Actions tab on GitHub
10+
workflow_dispatch:
11+
12+
env:
13+
# Name of module and id separated by a slash
14+
INSTANCE: docs/docs
15+
# Replace HI with the ID of the instance in capital letters
16+
ARTIFACT: webHelpDOCS2-all.zip
17+
# Writerside docker image version
18+
DOCKER_VERSION: '2025.04.8412'
19+
# Add the variable below to upload Algolia indexes
20+
# Replace HI with the ID of the instance in capital letters
21+
# ALGOLIA_ARTIFACT: algolia-indexes-HI.zip
22+
IS_GROUP: true
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
32+
- name: Build Writerside docs using Docker
33+
uses: JetBrains/writerside-github-action@v4
34+
with:
35+
instance: ${{ env.INSTANCE }}
36+
artifact: ${{ env.ARTIFACT }}
37+
docker-version: ${{ env.DOCKER_VERSION }}
38+
is-group: ${{ env.IS_GROUP }}
39+
40+
- name: Upload documentation
41+
uses: actions/upload-artifact@v4
42+
with:
43+
name: docs
44+
path: |
45+
artifacts/${{ env.ARTIFACT }}
46+
artifacts/report.json
47+
retention-days: 7
48+
49+
- name: Upload documentation test reports
50+
uses: actions/upload-artifact@v4
51+
if: ${{ always() }}
52+
with:
53+
name: 'report.json'
54+
path: |
55+
artifacts/report.json
56+
retention-days: 7
57+
58+
# Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors
59+
test:
60+
name: Test documentation built
61+
# Requires build job results
62+
needs: build
63+
runs-on: ubuntu-latest
64+
65+
steps:
66+
- name: Download artifacts
67+
uses: actions/download-artifact@v4
68+
with:
69+
name: docs
70+
path: artifacts
71+
72+
- name: Test documentation
73+
uses: JetBrains/writerside-checker-action@v1
74+
with:
75+
instance: ${{ env.INSTANCE }}
76+
is-group: ${{ env.IS_GROUP }}
77+
78+
- name: Unzip artifact
79+
run: unzip -O UTF-8 -qq artifacts/${{ env.ARTIFACT }} -d dir
80+
81+
- name: Upload dist
82+
uses: actions/upload-artifact@v4
83+
with:
84+
name: dist
85+
path: dir
86+
retention-days: 7

‎build.gradle.kts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,5 @@ tasks.create("createChangelog") {
5151
}
5252
}
5353
}
54+
55+
tasks.register<UpdateWritersideVersionTask>("updateWritersideVersion")

‎buildSrc/src/main/kotlin/UpdateWritersideVersionTask.kt‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import org.gradle.api.DefaultTask
2+
import org.gradle.api.tasks.TaskAction
3+
4+
abstract class UpdateWritersideVersionTask : DefaultTask() {
5+
/**
6+
* Update `<var name="version" value="xxx" />`'s value with current version
7+
* in docs_en/v.list` and `docs_zh/v.list`.
8+
*/
9+
@TaskAction
10+
fun action() {
11+
val currentVersion = IProject.version
12+
13+
// Update version in both Writerside v.list files
14+
val vListFiles = listOf(
15+
project.file("docs_en/v.list"),
16+
project.file("docs_zh/v.list")
17+
)
18+
19+
vListFiles.forEach { file ->
20+
if (file.exists()) {
21+
val content = file.readText()
22+
// Use regex to replace only the version variable's value attribute
23+
val updatedContent = content.replaceFirst(
24+
Regex("""(<var\s+name="version"\s+value=")[^"]*("\s*/>)"""),
25+
"$1$currentVersion$2"
26+
)
27+
file.writeText(updatedContent)
28+
project.logger.info("Updated version to {} in {}", currentVersion, file.path)
29+
} else {
30+
project.logger.warn("Warning: {} does not exist", file.path)
31+
}
32+
}
33+
}
34+
}

‎docs/cfg/build-groups.xml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE build-groups SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-groups.dtd">
3+
<build-groups xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-groups.xsd"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
5+
<build-group name="docs">
6+
<instance instance-id="den" alias="Kotlin Suspend Transform | Documentation" path="/en"/>
7+
<instance instance-id="dzh" alias="Kotlin Suspend Transform | 文档" path="/zh"/>
8+
</build-group>
9+
</build-groups>

‎docs/cfg/buildprofiles.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
3+
<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
5+
6+
<variables></variables>
7+
</buildprofiles>

‎docs/docs_libraries.tree‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE instance-profile
3+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
4+
5+
<instance-profile id="docs_libraries"
6+
name="docs_libraries"
7+
is-library="true"
8+
start-page="snippets.topic">
9+
10+
<toc-element topic="snippets.topic"/>
11+
</instance-profile>

‎docs/images/cover.png‎

103 KB
Loading

‎docs/topics/snippets.topic‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?xml version='1.0' encoding='UTF-8'?>
2+
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/html-entities.dtd">
3+
<topic xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" is-library="true" id="snippets" title="snippets"
5+
help-id="snippets">
6+
<!-- Put your snippets here -->
7+
<snippet id="cover-image">
8+
<img src="cover.png" alt="cover"/>
9+
</snippet>
10+
11+
<snippet id="gradle-plugin-dsl">
12+
<code-block lang="Kotlin">
13+
plugins {
14+
kotlin("jvm") version "$KOTLIN_VERSION" // or multiplatform
15+
id("love.forte.plugin.suspend-transform") version "%version%"
16+
// Others ...
17+
}
18+
</code-block>
19+
</snippet>
20+
21+
<snippet id="gradle-plugin-legacy">
22+
<code-block lang="Kotlin">
23+
buildscript {
24+
repositories {
25+
mavenCentral()
26+
gradlePluginPortal()
27+
}
28+
dependencies {
29+
classpath("love.forte.plugin.suspend-transform:suspend-transform-plugin-gradle:%version%")
30+
}
31+
}
32+
33+
plugins {
34+
id("org.jetbrains.kotlin.jvm") // or multiplatform?
35+
id("love.forte.plugin.suspend-transform")
36+
// Others ...
37+
}
38+
</code-block>
39+
</snippet>
40+
</topic>

‎docs/v.list‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
<vars>
2+
</vars>

0 commit comments

Comments
 (0)