diff options
author | Kristóf Marussy <kristof@marussy.com> | 2024-04-08 16:20:58 +0200 |
---|---|---|
committer | Kristóf Marussy <kristof@marussy.com> | 2024-04-08 17:52:35 +0200 |
commit | f862867a07fb09085a28bf134eb42276fde26540 (patch) | |
tree | b84f08003f0c143e27c3e3a339ab53f2aa339984 /subprojects/docs | |
parent | fix(language): Sonar lint issue (diff) | |
download | refinery-f862867a07fb09085a28bf134eb42276fde26540.tar.gz refinery-f862867a07fb09085a28bf134eb42276fde26540.tar.zst refinery-f862867a07fb09085a28bf134eb42276fde26540.zip |
docs: add Docusaurus website
Also refactor Yarn buildscripts.
Diffstat (limited to 'subprojects/docs')
-rw-r--r-- | subprojects/docs/.gitignore | 6 | ||||
-rw-r--r-- | subprojects/docs/babel.config.cts | 12 | ||||
-rw-r--r-- | subprojects/docs/build.gradle.kts | 91 | ||||
-rw-r--r-- | subprojects/docs/docusaurus.config.ts | 86 | ||||
-rw-r--r-- | subprojects/docs/package.json | 59 | ||||
-rw-r--r-- | subprojects/docs/src/css/custom.css | 40 | ||||
-rw-r--r-- | subprojects/docs/src/pages/index.tsx | 19 | ||||
-rw-r--r-- | subprojects/docs/src/plugins/swcMinifyPlugin.ts | 41 | ||||
-rw-r--r-- | subprojects/docs/tsconfig.json | 34 |
9 files changed, 388 insertions, 0 deletions
diff --git a/subprojects/docs/.gitignore b/subprojects/docs/.gitignore new file mode 100644 index 00000000..2d94aa21 --- /dev/null +++ b/subprojects/docs/.gitignore | |||
@@ -0,0 +1,6 @@ | |||
1 | # SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
2 | # | ||
3 | # SPDX-License-Identifier: CC0-1.0 | ||
4 | |||
5 | .docusaurus | ||
6 | .yarn | ||
diff --git a/subprojects/docs/babel.config.cts b/subprojects/docs/babel.config.cts new file mode 100644 index 00000000..b1bc1281 --- /dev/null +++ b/subprojects/docs/babel.config.cts | |||
@@ -0,0 +1,12 @@ | |||
1 | /* | ||
2 | * Copyright (c) Facebook, Inc. and its affiliates. | ||
3 | * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/> | ||
4 | * | ||
5 | * SPDX-License-Identifier: MIT AND EPL-2.0 | ||
6 | */ | ||
7 | |||
8 | import type { TransformOptions } from '@babel/core'; | ||
9 | |||
10 | module.exports = { | ||
11 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')], | ||
12 | } satisfies TransformOptions; | ||
diff --git a/subprojects/docs/build.gradle.kts b/subprojects/docs/build.gradle.kts new file mode 100644 index 00000000..9226ffe0 --- /dev/null +++ b/subprojects/docs/build.gradle.kts | |||
@@ -0,0 +1,91 @@ | |||
1 | /* | ||
2 | * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/> | ||
3 | * | ||
4 | * SPDX-License-Identifier: EPL-2.0 | ||
5 | */ | ||
6 | |||
7 | import org.siouan.frontendgradleplugin.infrastructure.gradle.RunYarn | ||
8 | import tools.refinery.gradle.utils.SonarPropertiesUtils | ||
9 | |||
10 | plugins { | ||
11 | id("tools.refinery.gradle.frontend-workspace") | ||
12 | id("tools.refinery.gradle.sonarqube") | ||
13 | } | ||
14 | |||
15 | frontend { | ||
16 | assembleScript.set("run build") | ||
17 | } | ||
18 | |||
19 | val srcDir = "src" | ||
20 | |||
21 | val docusaurusOutputDir = layout.buildDirectory.dir("docusaurus") | ||
22 | |||
23 | val configFiles: FileCollection = files( | ||
24 | rootProject.file("yarn.lock"), | ||
25 | rootProject.file("package.json"), | ||
26 | "package.json", | ||
27 | rootProject.file("tsconfig.base.json"), | ||
28 | "tsconfig.json", | ||
29 | "babel.config.config.ts", | ||
30 | "docusaurus.config.ts", | ||
31 | ) | ||
32 | |||
33 | val lintConfigFiles: FileCollection = configFiles + files( | ||
34 | rootProject.file(".eslintrc.cjs"), | ||
35 | rootProject.file("prettier.config.cjs") | ||
36 | ) | ||
37 | |||
38 | tasks { | ||
39 | assembleFrontend { | ||
40 | inputs.dir("src") | ||
41 | inputs.files(configFiles) | ||
42 | outputs.dir(docusaurusOutputDir) | ||
43 | } | ||
44 | |||
45 | val typeCheckFrontend by registering(RunYarn::class) { | ||
46 | dependsOn(installFrontend) | ||
47 | inputs.dir(srcDir) | ||
48 | inputs.files(configFiles) | ||
49 | outputs.dir(layout.buildDirectory.dir("typescript")) | ||
50 | script.set("run typecheck") | ||
51 | group = "verification" | ||
52 | description = "Check for TypeScript type errors." | ||
53 | } | ||
54 | |||
55 | val lintFrontend by registering(RunYarn::class) { | ||
56 | dependsOn(installFrontend) | ||
57 | dependsOn(typeCheckFrontend) | ||
58 | inputs.dir(srcDir) | ||
59 | inputs.files(lintConfigFiles) | ||
60 | outputs.file(layout.buildDirectory.file("eslint.json")) | ||
61 | script.set("run lint") | ||
62 | group = "verification" | ||
63 | description = "Check for TypeScript lint errors and warnings." | ||
64 | } | ||
65 | |||
66 | register<RunYarn>("fixFrontend") { | ||
67 | dependsOn(installFrontend) | ||
68 | dependsOn(typeCheckFrontend) | ||
69 | inputs.dir(srcDir) | ||
70 | inputs.files(lintConfigFiles) | ||
71 | script.set("run lint:fix") | ||
72 | group = "verification" | ||
73 | description = "Check for TypeScript lint errors and warnings." | ||
74 | } | ||
75 | |||
76 | check { | ||
77 | dependsOn(typeCheckFrontend) | ||
78 | dependsOn(lintFrontend) | ||
79 | } | ||
80 | |||
81 | clean { | ||
82 | delete(".docusaurus") | ||
83 | delete(".yarn") | ||
84 | } | ||
85 | } | ||
86 | |||
87 | sonarqube.properties { | ||
88 | SonarPropertiesUtils.addToList(properties, "sonar.sources", srcDir) | ||
89 | property("sonar.nodejs.executable", "${frontend.nodeInstallDirectory.get()}/bin/node") | ||
90 | property("sonar.eslint.reportPaths", "${layout.buildDirectory.get()}/eslint.json") | ||
91 | } | ||
diff --git a/subprojects/docs/docusaurus.config.ts b/subprojects/docs/docusaurus.config.ts new file mode 100644 index 00000000..d0f1b33a --- /dev/null +++ b/subprojects/docs/docusaurus.config.ts | |||
@@ -0,0 +1,86 @@ | |||
1 | /* | ||
2 | * Copyright (c) Facebook, Inc. and its affiliates. | ||
3 | * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/> | ||
4 | * | ||
5 | * SPDX-License-Identifier: MIT AND EPL-2.0 | ||
6 | */ | ||
7 | |||
8 | import type { Options as PagesOptions } from '@docusaurus/plugin-content-pages'; | ||
9 | import type { Options as ClassicThemeOptions } from '@docusaurus/theme-classic'; | ||
10 | import type { UserThemeConfig } from '@docusaurus/theme-common'; | ||
11 | import type { Config } from '@docusaurus/types'; | ||
12 | import { Config as SwcConfig } from '@swc/core'; | ||
13 | import smartypants from 'remark-smartypants'; | ||
14 | |||
15 | const markdownOptions = { | ||
16 | remarkPlugins: [[smartypants, { dashes: 'oldschool' }]], | ||
17 | }; | ||
18 | |||
19 | export default { | ||
20 | title: 'Refinery', | ||
21 | url: 'https://refinery.tools', | ||
22 | baseUrl: '/', | ||
23 | baseUrlIssueBanner: false, | ||
24 | trailingSlash: true, | ||
25 | staticDirectories: ['static'], | ||
26 | plugins: [ | ||
27 | [ | ||
28 | '@docusaurus/plugin-content-pages', | ||
29 | markdownOptions satisfies PagesOptions, | ||
30 | ], | ||
31 | '@docusaurus/plugin-sitemap', | ||
32 | './src/plugins/swcMinifyPlugin.ts', | ||
33 | ], | ||
34 | themes: [ | ||
35 | [ | ||
36 | '@docusaurus/theme-classic', | ||
37 | { | ||
38 | customCss: [require.resolve('./src/css/custom.css')], | ||
39 | } satisfies ClassicThemeOptions, | ||
40 | ], | ||
41 | ], | ||
42 | themeConfig: { | ||
43 | colorMode: { | ||
44 | respectPrefersColorScheme: true, | ||
45 | }, | ||
46 | navbar: { | ||
47 | title: 'Refinery', | ||
48 | hideOnScroll: true, | ||
49 | }, | ||
50 | footer: { | ||
51 | copyright: ` | ||
52 | Copyright © 2021-2024 | ||
53 | <a href="https://github.com/graphs4value/refinery/blob/main/CONTRIBUTORS.md" target="_blank">The Refinery Authors</a>. | ||
54 | Available under the | ||
55 | <a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">Eclipse Public License - v 2.0</a>. | ||
56 | `, | ||
57 | }, | ||
58 | } satisfies UserThemeConfig, | ||
59 | webpack: { | ||
60 | // Speed up builds by using a native Javascript loader. | ||
61 | // See: https://github.com/facebook/docusaurus/issues/4765#issuecomment-841135926 | ||
62 | // But we follow the Docusaurus upstream from | ||
63 | // https://github.com/facebook/docusaurus/blob/791da2e4a1a53aa6309887059e3f112fcb35bec4/website/docusaurus.config.ts#L152-L171 | ||
64 | // and use swc instead of esbuild. | ||
65 | jsLoader: (isServer) => ({ | ||
66 | loader: require.resolve('swc-loader'), | ||
67 | options: { | ||
68 | jsc: { | ||
69 | parser: { | ||
70 | syntax: 'typescript', | ||
71 | tsx: true, | ||
72 | }, | ||
73 | transform: { | ||
74 | react: { | ||
75 | runtime: 'automatic', | ||
76 | }, | ||
77 | }, | ||
78 | target: 'es2022', | ||
79 | }, | ||
80 | module: { | ||
81 | type: isServer ? 'commonjs' : 'es6', | ||
82 | }, | ||
83 | } satisfies SwcConfig, | ||
84 | }), | ||
85 | }, | ||
86 | } satisfies Config; | ||
diff --git a/subprojects/docs/package.json b/subprojects/docs/package.json new file mode 100644 index 00000000..bdf95a70 --- /dev/null +++ b/subprojects/docs/package.json | |||
@@ -0,0 +1,59 @@ | |||
1 | { | ||
2 | "//": [ | ||
3 | "SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>", | ||
4 | "", | ||
5 | "SPDX-License-Identifier: EPL-2.0" | ||
6 | ], | ||
7 | "name": "@refinery/docs", | ||
8 | "version": "0.0.0", | ||
9 | "description": "Documentation for Refinery", | ||
10 | "private": true, | ||
11 | "scripts": { | ||
12 | "build": "WEBPACK_URL_LOADER_LIMIT=0 docusaurus build --out-dir build/docusaurus", | ||
13 | "serve": "docusaurus serve --dir build/docusaurus --port 1313 --no-open", | ||
14 | "dev": "WEBPACK_URL_LOADER_LIMIT=0 docusaurus start --port 1313 --no-open", | ||
15 | "docusaurus": "docusaurus", | ||
16 | "write-translations": "docusaurus write-translations", | ||
17 | "write-heading-ids": "docusaurus write-heading-ids", | ||
18 | "typecheck": "yarn run g:tsc -p subprojects/docs/tsconfig.json", | ||
19 | "lint": "yarn run g:lint subprojects/docs", | ||
20 | "lint:fix": "yarn run lint --fix" | ||
21 | }, | ||
22 | "repository": { | ||
23 | "type": "git", | ||
24 | "url": "git+https://github.com/graphs4value/refinery.git" | ||
25 | }, | ||
26 | "author": "The Refinery Authors <https://refinery.tools/>", | ||
27 | "license": "EPL-2.0", | ||
28 | "bugs": { | ||
29 | "url": "https://github.com/graphs4value/refinery/issues" | ||
30 | }, | ||
31 | "homepage": "https://refinery.tools", | ||
32 | "dependencies": { | ||
33 | "@docusaurus/core": "^3.2.1", | ||
34 | "@docusaurus/plugin-content-docs": "^3.2.1", | ||
35 | "@docusaurus/plugin-content-pages": "^3.2.1", | ||
36 | "@docusaurus/plugin-sitemap": "^3.2.1", | ||
37 | "@docusaurus/theme-classic": "^3.2.1", | ||
38 | "@docusaurus/theme-common": "^3.2.1", | ||
39 | "@fontsource-variable/jetbrains-mono": "^5.0.20", | ||
40 | "@fontsource-variable/open-sans": "^5.0.28", | ||
41 | "@fontsource/open-sans": "^5.0.27", | ||
42 | "@mdx-js/react": "^3.0.1", | ||
43 | "@swc/core": "^1.4.12", | ||
44 | "react": "^18.2.0", | ||
45 | "react-dom": "^18.2.0", | ||
46 | "remark-smartypants": "^2.1.0", | ||
47 | "swc-loader": "^0.2.6", | ||
48 | "terser-webpack-plugin": "^5.3.10", | ||
49 | "webpack": "^5.91.0" | ||
50 | }, | ||
51 | "devDependencies": { | ||
52 | "@docusaurus/module-type-aliases": "^3.2.1", | ||
53 | "@docusaurus/types": "^3.2.1", | ||
54 | "@types/babel__core": "^7.20.5", | ||
55 | "@types/node": "^20.12.5", | ||
56 | "@types/react": "^18.2.74", | ||
57 | "@types/react-dom": "^18.2.24" | ||
58 | } | ||
59 | } | ||
diff --git a/subprojects/docs/src/css/custom.css b/subprojects/docs/src/css/custom.css new file mode 100644 index 00000000..115d7ac9 --- /dev/null +++ b/subprojects/docs/src/css/custom.css | |||
@@ -0,0 +1,40 @@ | |||
1 | /* | ||
2 | * SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | * | ||
4 | * SPDX-License-Identifier: EPL-2.0 | ||
5 | */ | ||
6 | |||
7 | @import '@fontsource-variable/open-sans/wdth.css'; | ||
8 | @import '@fontsource-variable/open-sans/wdth-italic.css'; | ||
9 | @import '@fontsource-variable/jetbrains-mono/wght.css'; | ||
10 | @import '@fontsource-variable/jetbrains-mono/wght-italic.css'; | ||
11 | |||
12 | :root { | ||
13 | --ifm-font-family-base: 'Open Sans Variable', | ||
14 | 'Open Sans', | ||
15 | 'Roboto', | ||
16 | 'Helvetica', | ||
17 | 'Arial', | ||
18 | sans-serif; | ||
19 | --ifm-fony-family-monospace: 'JetBrains Mono Variable', | ||
20 | 'JetBrains Mono', | ||
21 | 'Cascadia Code', | ||
22 | 'Fira Code', | ||
23 | monospace; | ||
24 | --ifm-code-font-size: 95%; | ||
25 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); | ||
26 | } | ||
27 | |||
28 | [data-theme='dark'] { | ||
29 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); | ||
30 | } | ||
31 | |||
32 | code, | ||
33 | kbd { | ||
34 | font-feature-settings: 'liga', 'calt'; | ||
35 | } | ||
36 | |||
37 | .navbar__title { | ||
38 | font-weight: 500; | ||
39 | font-size: 1.25rem; | ||
40 | } | ||
diff --git a/subprojects/docs/src/pages/index.tsx b/subprojects/docs/src/pages/index.tsx new file mode 100644 index 00000000..256d12ac --- /dev/null +++ b/subprojects/docs/src/pages/index.tsx | |||
@@ -0,0 +1,19 @@ | |||
1 | /* | ||
2 | * SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | * | ||
4 | * SPDX-License-Identifier: EPL-2.0 | ||
5 | */ | ||
6 | |||
7 | import Layout from '@theme/Layout'; | ||
8 | |||
9 | export default function Home() { | ||
10 | return ( | ||
11 | <Layout> | ||
12 | <div className="hero hero--dark"> | ||
13 | <div className="container"> | ||
14 | <h1 className="hero__title">Refinery</h1> | ||
15 | </div> | ||
16 | </div> | ||
17 | </Layout> | ||
18 | ); | ||
19 | } | ||
diff --git a/subprojects/docs/src/plugins/swcMinifyPlugin.ts b/subprojects/docs/src/plugins/swcMinifyPlugin.ts new file mode 100644 index 00000000..ecac654b --- /dev/null +++ b/subprojects/docs/src/plugins/swcMinifyPlugin.ts | |||
@@ -0,0 +1,41 @@ | |||
1 | /* | ||
2 | * SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | * | ||
4 | * SPDX-License-Identifier: EPL-2.0 | ||
5 | */ | ||
6 | |||
7 | import type { Plugin } from '@docusaurus/types'; | ||
8 | import TerserPlugin from 'terser-webpack-plugin'; | ||
9 | |||
10 | /** | ||
11 | * A Docusarus plugin that replaces the built-in Javascript minifier with swc. | ||
12 | * | ||
13 | * See | ||
14 | * https://github.com/facebook/docusaurus/issues/4765#issuecomment-1679863984 | ||
15 | * but we use swc instead of esbuild. | ||
16 | * | ||
17 | * @returns The Docusarus plugin. | ||
18 | */ | ||
19 | export default function swcMinifyPlugin(): Plugin { | ||
20 | return { | ||
21 | name: 'refinery-swc-minify-plugin', | ||
22 | configureWebpack: (config) => ({ | ||
23 | mergeStrategy: { | ||
24 | 'optimization.minimizer': 'replace', | ||
25 | }, | ||
26 | optimization: { | ||
27 | minimizer: | ||
28 | config.optimization?.minimizer?.map((plugin) => { | ||
29 | // `instanceof` seems to be broken, because a different version of | ||
30 | // `TerserPlguin` is coming from Docusaurus than the one we import. | ||
31 | if (plugin?.constructor.name === TerserPlugin.name) { | ||
32 | return new TerserPlugin({ | ||
33 | minify: TerserPlugin.swcMinify, | ||
34 | }); | ||
35 | } | ||
36 | return plugin; | ||
37 | }) ?? [], | ||
38 | }, | ||
39 | }), | ||
40 | }; | ||
41 | } | ||
diff --git a/subprojects/docs/tsconfig.json b/subprojects/docs/tsconfig.json new file mode 100644 index 00000000..5b32bb0e --- /dev/null +++ b/subprojects/docs/tsconfig.json | |||
@@ -0,0 +1,34 @@ | |||
1 | /* | ||
2 | * Copyright (c) Facebook, Inc. and its affiliates. | ||
3 | * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/> | ||
4 | * | ||
5 | * SPDX-License-Identifier: MIT AND EPL-2.0 | ||
6 | * | ||
7 | * FIle based on | ||
8 | * https://github.com/facebook/docusaurus/blob/73016d4936164ba38d4b86ec2aa8c168b5904a21/packages/docusaurus-tsconfig/tsconfig.json | ||
9 | * but copied instead of adding an `extends` declaration to let SonarQube see its contents. | ||
10 | */ | ||
11 | { | ||
12 | "extends": "../../tsconfig.base.json", | ||
13 | "compilerOptions": { | ||
14 | "jsx": "preserve", | ||
15 | "module": "esnext", | ||
16 | "moduleResolution": "bundler", | ||
17 | "lib": ["DOM", "DOM.Iterable", "ES2022"], | ||
18 | "types": [ | ||
19 | "node", | ||
20 | "@docusaurus/module-type-aliases", | ||
21 | "@docusaurus/theme-classic" | ||
22 | ], | ||
23 | "baseUrl": ".", | ||
24 | "paths": { | ||
25 | "@site/*": ["./*"] | ||
26 | } | ||
27 | }, | ||
28 | "include": ["."], | ||
29 | "exclude": [ | ||
30 | ".docusaurus", | ||
31 | ".yarn", | ||
32 | "build" | ||
33 | ] | ||
34 | } | ||