Skip to content

Commit bc38dac

Browse files
ryyppyryyppy
committed
Migrate Manual Docs to new Layout architecture
- Add data/sidebar_manual_latest.json - Add data/sidebar_manual_v800.json - Use DocsLayout.Make - Inline Latest / V800 into one ManualDocsLayout module - Adapt some page meta data - Fix meta data for build configuration schema page
1 parent 2e778c7 commit bc38dac

28 files changed

+463
-1163
lines changed

‎data/sidebar_manual_latest.json

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"Overview": [
3+
"introduction",
4+
"installation",
5+
"editor-plugins",
6+
"migrate-from-bucklescript-reason",
7+
"try"
8+
],
9+
"Language Features": [
10+
"overview",
11+
"let-binding",
12+
"type",
13+
"primitive-types",
14+
"tuple",
15+
"record",
16+
"object",
17+
"variant",
18+
"null-undefined-option",
19+
"array-and-list",
20+
"function",
21+
"control-flow",
22+
"pipe",
23+
"pattern-matching-destructuring",
24+
"mutation",
25+
"jsx",
26+
"exception",
27+
"lazy-values",
28+
"promise",
29+
"module",
30+
"import-export",
31+
"attribute",
32+
"unboxed",
33+
"reserved-keywords"
34+
],
35+
"JavaScript Interop": [
36+
"embed-raw-javascript",
37+
"shared-data-types",
38+
"external",
39+
"bind-to-js-object",
40+
"bind-to-js-function",
41+
"import-from-export-to-js",
42+
"bind-to-global-js-values",
43+
"json",
44+
"inlining-constants",
45+
"use-illegal-identifier-names",
46+
"generate-converters-accessors",
47+
"browser-support-polyfills",
48+
"interop-cheatsheet"
49+
],
50+
"Build System": [
51+
"build-overview",
52+
"build-configuration",
53+
"build-configuration-schema",
54+
"interop-with-js-build-systems",
55+
"build-performance"
56+
],
57+
"Guides": [
58+
"converting-from-js",
59+
"libraries"
60+
],
61+
"Extra": [
62+
"newcomer-examples",
63+
"project-structure",
64+
"faq"
65+
]
66+
}

‎data/sidebar_manual_v800.json

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
{
2+
"Overview": [
3+
"introduction",
4+
"installation",
5+
"editor-plugins",
6+
"migrate-from-bucklescript-reason",
7+
"try"
8+
],
9+
"Language Features": [
10+
"overview",
11+
"let-binding",
12+
"type",
13+
"primitive-types",
14+
"tuple",
15+
"record",
16+
"object",
17+
"variant",
18+
"null-undefined-option",
19+
"array-and-list",
20+
"function",
21+
"control-flow",
22+
"pipe",
23+
"pattern-matching-destructuring",
24+
"mutation",
25+
"jsx",
26+
"exception",
27+
"lazy-values",
28+
"promise",
29+
"module",
30+
"import-export",
31+
"reserved-keywords"
32+
],
33+
"JavaScript Interop": [
34+
"embed-raw-javascript",
35+
"shared-data-types",
36+
"external",
37+
"bind-to-js-object",
38+
"bind-to-js-function",
39+
"import-from-export-to-js",
40+
"bind-to-global-js-values",
41+
"json",
42+
"use-illegal-identifier-names",
43+
"generate-converters-accessors",
44+
"browser-support-polyfills",
45+
"interop-cheatsheet"
46+
],
47+
"Build System": [
48+
"build-overview",
49+
"build-configuration",
50+
"interop-with-js-build-systems",
51+
"build-performance"
52+
],
53+
"Guides": [
54+
"converting-from-js",
55+
"libraries"
56+
],
57+
"Extra": [
58+
"newcomer-examples",
59+
"project-structure",
60+
"faq"
61+
]
62+
}

‎pages/_app.js

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
//}
88

99
import "styles/main.css";
10-
import {make as App} from "src/common/App.js";
10+
import {make as ResApp} from "src/common/App.js";
1111

12-
export default App;
12+
export default function App(props) {
13+
return <ResApp {...props} />
14+
};

‎pages/docs/manual/latest/build-configuration-schema.js

Lines changed: 0 additions & 14 deletions
This file was deleted.

‎pages/docs/manual/latest/build-configuration-schema.mdx

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: "Configuration Schema"
3+
metaTitle: "Build System Configuration Schema"
4+
description: "Schema exploration widget for the ReScript configuration file"
5+
canonical: "/docs/manual/latest/build-configuration-schema"
6+
---
7+
8+
import dynamic from "next/dynamic";
9+
10+
export const Docson = dynamic(() => import("src/components/Docson").then((comp) => {
11+
return comp.make;
12+
}), {
13+
ssr: false,
14+
loading: () => <div> Loading... </div>
15+
});
16+
17+
export default function BuildConfigurationSchemaPage() {
18+
return <Docson/>;
19+
}

‎pages/docs/manual/latest/build-configuration.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: "Build System Configuration"
2+
title: "Configuration"
3+
metaTitle: "Build System Configuration"
34
description: "Details about the configuration of the ReScript build system (bsconfig.json)"
45
canonical: "/docs/manual/latest/build-configuration"
56
---

‎pages/docs/manual/latest/build-overview.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: "Build System Overview"
2+
title: "Overview"
3+
metaTitle: "Build System Overview"
34
description: "Documentation about the ReScript build system and its toolchain"
45
canonical: "/docs/manual/latest/build-overview"
56
---

‎pages/docs/manual/latest/build-performance.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: "Build Performance"
2+
title: "Performance"
3+
metaTitle: "Build Performance"
34
description: "ReScript build performance and measuring tools"
45
canonical: "/docs/manual/latest/build-performance"
56
---

‎pages/docs/manual/latest/introduction.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "ReScript Introduction"
2+
title: "Introduction"
33
description: "The hows and whys of ReScript"
44
canonical: "/docs/manual/latest/introduction"
55
---

‎pages/docs/manual/latest/overview.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: "Language Features Overview"
2+
title: "Overview"
3+
metaTitle: "Language Features Overview"
34
description: "A quick overview on ReScript's syntax"
45
canonical: "/docs/manual/latest/overview"
56
---

‎pages/docs/manual/latest/promise.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Promise"
2+
title: "Async & Promise"
33
description: "JS Promise handling in ReScript"
44
canonical: "/docs/manual/latest/promise"
55
---

‎pages/docs/manual/latest/unboxed.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ description: "Unbox a wrapper"
44
canonical: "/docs/manual/latest/unboxed"
55
---
66

7+
# Unboxed
8+
79
Consider a ReScript variant with a single payload, and a record with a single field:
810

911
<CodeTab labels={["ReScript", "JS Output"]}>

‎pages/docs/manual/v8.0.0/introduction.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "ReScript Introduction"
2+
title: "Introduction"
33
description: "The hows and whys of ReScript"
44
canonical: "/docs/manual/latest/introduction"
55
---

‎pages/docs/manual/v8.0.0/overview.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: "Language Features Overview"
2+
title: "Overview"
3+
metaTitle: "Language Features Overview"
34
description: "A quick overview on ReScript's syntax"
45
canonical: "/docs/manual/latest/overview"
56
---

‎scripts/extract-tocs.js

Lines changed: 45 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,15 @@ const orderFiles = (filepaths, orderArr) => {
2323
order[id] = filepath;
2424
});
2525

26+
// last sanity check if there's an unmatched filepath
27+
Object.entries(order).forEach(([name, filepath]) => {
28+
// may happen e.g. due to invalid file paths within
29+
// sidebar json
30+
if(filepath == null) {
31+
throw new Error(`Cannot find file for "${name}". Does it exist in the pages folder?`);
32+
}
33+
});
34+
2635
return Object.values(order);
2736
};
2837

@@ -68,7 +77,8 @@ const processor = unified()
6877
.use(stringify)
6978
.use(headers);
7079

71-
const processFile = filepath => {
80+
// sidebarJson: { [category: string]: array<plain_filename_without_ext> }
81+
const processFile = (filepath, sidebarJson={}) => {
7282
const raw = fs.readFileSync(filepath, "utf8");
7383
const { content, data } = matter(raw);
7484
const result = processor.processSync(content);
@@ -78,7 +88,15 @@ const processFile = filepath => {
7888
const parsedPath = path.parse(relFilepath);
7989
const filename = path.basename(filepath, path.extname(filepath));
8090

81-
let title = result.data.mainHeader || data.title || filename;
91+
const title = data.title || result.data.mainHeader || filename;
92+
93+
let category;
94+
for (const [categoryName, items] of Object.entries(sidebarJson)) {
95+
if(items.find((item) => filename === item)){
96+
category = categoryName;
97+
break;
98+
}
99+
}
82100

83101
const dataset = {
84102
id: filename,
@@ -87,8 +105,8 @@ const processFile = filepath => {
87105
title,
88106
};
89107

90-
if(data.category != null) {
91-
dataset.category = data.category;
108+
if(category != null) {
109+
dataset.category = category;
92110
}
93111
return dataset;
94112
};
@@ -112,10 +130,19 @@ const createTOC = result => {
112130

113131
const createLatestManualToc = () => {
114132
const MD_DIR = path.join(__dirname, "../pages/docs/manual/latest");
115-
const TARGET_FILE = path.join(__dirname, "../index_data/manual_toc.json");
133+
const SIDEBAR_JSON = path.join(__dirname, "../data/sidebar_manual_latest.json");
134+
const TARGET_FILE = path.join(__dirname, "../index_data/manual_latest_toc.json");
116135

117-
const files = glob.sync(`${MD_DIR}/*.md?(x)`);
118-
const result = files.map(processFile);
136+
const sidebarJson = JSON.parse(fs.readFileSync(SIDEBAR_JSON));
137+
138+
const FILE_ORDER = Object.values(sidebarJson).reduce((acc, items) => {
139+
return acc.concat(items)
140+
},[]);
141+
142+
const files = glob.sync(`${MD_DIR}/*.?(js|md?(x))`);
143+
const ordered = orderFiles(files, FILE_ORDER);
144+
145+
const result = ordered.map((filepath) => processFile(filepath, sidebarJson));
119146
const toc = createTOC(result);
120147

121148
fs.writeFileSync(TARGET_FILE, JSON.stringify(toc), "utf8");
@@ -134,10 +161,19 @@ const createReasonCompilerToc = () => {
134161

135162
const createV800ManualToc = () => {
136163
const MD_DIR = path.join(__dirname, "../pages/docs/manual/v8.0.0");
164+
const SIDEBAR_JSON = path.join(__dirname, "../data/sidebar_manual_v800.json");
137165
const TARGET_FILE = path.join(__dirname, "../index_data/manual_v800_toc.json");
138166

139-
const files = glob.sync(`${MD_DIR}/*.md?(x)`);
140-
const result = files.map(processFile);
167+
const sidebarJson = JSON.parse(fs.readFileSync(SIDEBAR_JSON));
168+
169+
const FILE_ORDER = Object.values(sidebarJson).reduce((acc, items) => {
170+
return acc.concat(items)
171+
},[]);
172+
173+
const files = glob.sync(`${MD_DIR}/*.?(js|md?(x))`);
174+
const ordered = orderFiles(files, FILE_ORDER);
175+
176+
const result = ordered.map((filepath) => processFile(filepath, sidebarJson));
141177
const toc = createTOC(result);
142178

143179
fs.writeFileSync(TARGET_FILE, JSON.stringify(toc), "utf8");

‎src/common/App.js

Lines changed: 2 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/common/App.res

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,13 +84,13 @@ let make = (props: props): React.element => {
8484
| _ =>
8585
switch version {
8686
| Latest =>
87-
<ManualDocsLayout.Prose frontmatter={component->frontmatter}>
87+
<ManualDocsLayout.Latest frontmatter={component->frontmatter}>
8888
content
89-
</ManualDocsLayout.Prose>
89+
</ManualDocsLayout.Latest>
9090
| Version("v8.0.0") =>
91-
<ManualDocsLayout8_0_0.Prose frontmatter={component->frontmatter}>
91+
<ManualDocsLayout.V800 frontmatter={component->frontmatter}>
9292
content
93-
</ManualDocsLayout8_0_0.Prose>
93+
</ManualDocsLayout.V800>
9494
| _ => React.null
9595
}
9696
}

‎src/common/DocFrontmatter.js

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)