Skip to content

Commit 5db3fc6

Browse files
nojafnojaf
committed
Unify API doc pages
1 parent 367af85 commit 5db3fc6

File tree

10 files changed

+220
-176
lines changed

10 files changed

+220
-176
lines changed

‎docs/components/apidoc.astro

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
import { apiModules, getDoc } from "../utils";
3+
import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
4+
import Value from "./value.astro";
5+
import Type from "./type.astro";
6+
7+
const { moduleName, filePath, link } = Astro.props;
8+
9+
const { types, typesInOwnModule, typeHeadings, values, valueHeadings } =
10+
await getDoc(filePath);
11+
12+
const frontmatter = {
13+
title: moduleName,
14+
};
15+
16+
const headings = [];
17+
if (types.length > 0) {
18+
headings.push({
19+
depth: 2,
20+
slug: "types",
21+
text: "Types",
22+
});
23+
headings.push(...typeHeadings);
24+
}
25+
26+
if (values.length > 0) {
27+
headings.push({
28+
depth: 2,
29+
slug: "values",
30+
text: "Values",
31+
});
32+
headings.push(...valueHeadings);
33+
}
34+
---
35+
<StarlightPage frontmatter={frontmatter} headings={headings}>
36+
{
37+
types.length > 0 && (
38+
<>
39+
<h2 id="types">Types</h2>
40+
{types.map((type) => (
41+
<Type
42+
type={type}
43+
typesInOwnModule={typesInOwnModule}
44+
filePath={filePath}
45+
link={link}
46+
/>
47+
))}
48+
</>
49+
)
50+
}
51+
{
52+
values.length > 0 && (
53+
<>
54+
<h2 id="values">Values</h2>
55+
{values.map((value) => <Value value={value} />)}
56+
</>
57+
)
58+
}
59+
</StarlightPage>

‎docs/components/record.astro

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ const { name, items, typesInOwnModule } = Astro.props;
4040
}
4141

4242
& .doc {
43+
margin-top: 0;
4344
padding-bottom: 0.5rem;
4445
grid-column: 1 / -1;
4546
grid-row: 2;

‎docs/components/type.astro

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
import * as path from "node:path";
3+
import { existsSync } from "node:fs";
4+
import { Code } from "@astrojs/starlight/components";
5+
import Record from "./record.astro";
6+
import { createTypeModuleLink } from "../utils";
7+
8+
const { type, typesInOwnModule, filePath, link } = Astro.props;
9+
10+
function showRecord(details) {
11+
return details && details.kind === "record" && details.items.length > 0;
12+
}
13+
14+
function getModuleFileName(typeName) {
15+
return `${typeName[0].toUpperCase()}${typeName.slice(1)}`;
16+
}
17+
18+
/**
19+
* Check if there is a file representing the module for the type.
20+
* The location to be checked is a sub directory with the same name as the current file type.
21+
* @param {string} typeName
22+
* @param {string} filePath
23+
* @returns {boolean}
24+
*/
25+
function showModule(typeName, filePath) {
26+
const moduleFileName = `${getModuleFileName(typeName)}.res`;
27+
const potentialPath = path.join(filePath.replace(".res", ""), moduleFileName);
28+
return existsSync(potentialPath);
29+
}
30+
---
31+
32+
<div class="rescript_type">
33+
<h3 id={type.name}>{type.name}</h3>
34+
<div set:html={type.documentation} />
35+
<Code lang="ReScript" code={type.signature} />
36+
{
37+
showRecord(type.detail) ? (
38+
<Record
39+
name={type.name}
40+
typesInOwnModule={typesInOwnModule}
41+
{...type.detail}
42+
/>
43+
) : null
44+
}
45+
{
46+
showModule(type.name, filePath) && (
47+
<>
48+
<h4>Module</h4>
49+
<p>
50+
There are methods and helpers defined in{" "}
51+
<a
52+
href={`${import.meta.env.BASE_URL}/${createTypeModuleLink(link, type.name)}`}
53+
>
54+
{getModuleFileName(type.name)}
55+
</a>
56+
.
57+
</p>
58+
</>
59+
)
60+
}
61+
</div>
62+
<style>
63+
.rescript_type {
64+
margin-block: 2rem;
65+
}
66+
</style>
67+

‎docs/components/value.astro

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,35 @@
11
---
2+
import { Code } from "@astrojs/starlight/components";
23
import SignatureItem from "./signatureItem.astro";
3-
const { parameters, returnType } = Astro.props;
4+
const { value } = Astro.props;
5+
const details = value.detail?.details || null;
6+
7+
function showValue(detail) {
8+
return detail?.kind === "signature" && detail.details?.parameters?.length > 0;
9+
}
10+
411
---
512

6-
<div class="value">
7-
<h4>Parameters</h4>
13+
<div class="rescript_value">
14+
<h3 id={value.name}>{value.name}</h3>
15+
<div set:html={value.documentation} />
16+
<Code lang="ReScript" code={value.signature} />
817
{
9-
parameters.map((p) => (
10-
<SignatureItem item={p} />
11-
))
18+
showValue(value.detail) && (
19+
<div class="value_detail">
20+
<h4>Parameters</h4>
21+
{details.parameters.map((p) => (
22+
<SignatureItem item={p} />
23+
))}
24+
<h4>Return type</h4>
25+
<SignatureItem item={details.returnType} />
26+
</div>
27+
)
1228
}
13-
<h4>Return type</h4>
14-
<SignatureItem item={returnType} />
1529
</div>
30+
1631
<style>
17-
.value {
32+
.value_detail {
1833
display: flex;
1934
flex-direction: column;
2035
padding-bottom: 1rem;

‎docs/pages/apidocs/[API].astro

Lines changed: 3 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
---
2-
import * as path from "node:path";
3-
import { existsSync } from "fs";
4-
import { apiModules, getDoc, createTypeModuleLink } from "../../utils";
5-
import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
6-
import { Code } from "@astrojs/starlight/components";
7-
import { micromark } from "micromark";
8-
import Record from "../../components/record.astro";
2+
import { apiModules } from "../../utils";
3+
import APIDoc from "../../components/apidoc.astro";
94
105
export async function getStaticPaths() {
116
return apiModules.map((apiModule) => {
@@ -18,97 +13,7 @@ export async function getStaticPaths() {
1813
});
1914
}
2015
21-
function showRecord(details) {
22-
return details && details.kind === "record" && details.items.length > 0;
23-
}
24-
25-
function getModuleFileName(typeName) {
26-
return `${typeName[0].toUpperCase()}${typeName.slice(1)}`;
27-
}
28-
29-
function showModule(typeName, filePath) {
30-
const moduleFileName = `${getModuleFileName(typeName)}.res`;
31-
const potentialPath = path.join(filePath.replace(".res", ""), moduleFileName);
32-
return existsSync(potentialPath);
33-
}
34-
3516
const { moduleName, filePath, link } = Astro.props;
36-
37-
const docInfo = await getDoc(filePath);
38-
39-
const types = docInfo.items
40-
.filter((item) => item.kind === "type")
41-
.sort((a, b) => a.name.localeCompare(b.name))
42-
.map((type) => {
43-
const documentation =
44-
type.docstrings && micromark(type.docstrings.join("\n"));
45-
return {
46-
name: type.name,
47-
documentation,
48-
signature: type.signature,
49-
detail: type.detail,
50-
};
51-
});
52-
53-
const typesInOwnModule = new Set(types.map((t) => t.name));
54-
55-
const typeHeadings = types.map((type) => ({
56-
depth: 3,
57-
slug: type.name,
58-
text: type.name,
59-
}));
60-
61-
const frontmatter = {
62-
title: moduleName,
63-
};
64-
65-
const headings = [
66-
{
67-
depth: 2,
68-
slug: "types",
69-
text: "Types",
70-
},
71-
...typeHeadings,
72-
];
7317
---
7418

75-
<StarlightPage frontmatter={frontmatter} headings={headings}>
76-
<div id="apidocs">
77-
<h2 id="types">Types</h2>
78-
{
79-
types.map((type) => (
80-
<div class="rescript_type">
81-
<h3 id={type.name}>{type.name}</h3>
82-
<div set:html={type.documentation} />
83-
<Code lang="ReScript" code={type.signature} />
84-
{showRecord(type.detail) ? (
85-
<Record
86-
name={type.name}
87-
typesInOwnModule={typesInOwnModule}
88-
{...type.detail}
89-
/>
90-
) : null}
91-
{showModule(type.name, filePath) && (
92-
<>
93-
<h4>Module</h4>
94-
<p>
95-
There are methods and helpers defined in{" "}
96-
<a
97-
href={`${import.meta.env.BASE_URL}/${createTypeModuleLink(link, type.name)}`}
98-
>
99-
{getModuleFileName(type.name)}
100-
</a>
101-
.
102-
</p>
103-
</>
104-
)}
105-
</div>
106-
))
107-
}
108-
</div>
109-
</StarlightPage>
110-
<style>
111-
#apidocs .rescript_type {
112-
margin-block: 2rem;
113-
}
114-
</style>
19+
<APIDoc moduleName={moduleName} filePath={filePath} link={link} />

‎docs/pages/apidocs/[API]/[Module].astro

Lines changed: 3 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
---
22
import { apiModules, getDoc } from "../../../utils";
3-
import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
4-
import { Code } from "@astrojs/starlight/components";
5-
import { micromark } from "micromark";
6-
import Value from "../../../components/value.astro";
3+
import APIDoc from "../../../components/apidoc.astro";
74
85
export async function getStaticPaths() {
96
return apiModules.flatMap((apiModule) => {
@@ -19,68 +16,7 @@ export async function getStaticPaths() {
1916
});
2017
}
2118
22-
function showValue(detail) {
23-
return (
24-
detail?.kind === "signature" && detail?.details?.parameters?.length > 0
25-
);
26-
}
27-
28-
const { filePath, moduleName } = Astro.props.currentModule;
29-
const docInfo = await getDoc(filePath);
30-
31-
const values = docInfo.items
32-
.filter((item) => item.kind === "value")
33-
.sort((a, b) => a.name.localeCompare(b.name))
34-
.map((value) => {
35-
const documentation =
36-
value.docstrings && micromark(value.docstrings.join("\n"));
37-
return {
38-
name: value.name,
39-
documentation,
40-
signature: value.signature,
41-
detail: value.detail,
42-
};
43-
});
44-
45-
const valueHeadings = values.map((value) => ({
46-
depth: 3,
47-
slug: value.name,
48-
text: value.name,
49-
}));
50-
51-
const frontmatter = {
52-
title: moduleName,
53-
};
54-
55-
const headings = [
56-
{
57-
depth: 2,
58-
slug: "values",
59-
text: "Values",
60-
},
61-
...valueHeadings,
62-
];
19+
const { filePath, moduleName, link } = Astro.props.currentModule;
6320
---
6421

65-
<StarlightPage frontmatter={frontmatter} headings={headings}>
66-
<h2 id="values">Values</h2>
67-
{
68-
values.map((value) => (
69-
<div class="rescript_value">
70-
<h3 id={value.name}>{value.name}</h3>
71-
<div set:html={value.documentation} />
72-
<Code lang="ReScript" code={value.signature} />
73-
{showValue(value.detail) && <Value {...value.detail.details} />}
74-
</div>
75-
))
76-
}
77-
<pre>
78-
{JSON.stringify(docInfo, null, 4)}
79-
</pre>
80-
</StarlightPage>
81-
<style>
82-
pre {
83-
max-width: 100%;
84-
overflow-x: auto;
85-
}
86-
</style>
22+
<APIDoc moduleName={moduleName} filePath={filePath} link={link} />

‎docs/styles/theme.css

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
::backdrop {
33
--sl-font: "Inter", "Roboto Mono";
44
--sl-sidebar-width: 23rem;
5+
--sl-text-3xl: 1.5rem;
6+
--sl-text-2xl: 1.3rem;
57
}
68

79
/*

0 commit comments

Comments
 (0)