Skip to content

Commit 82fded4

Browse files
WilsontheWolfWilsontheWolf
committed
chore: lots of docs fixes
1 parent 90c5260 commit 82fded4

File tree

17 files changed

+361
-102
lines changed

17 files changed

+361
-102
lines changed

‎astro.config.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ export default defineConfig({
1010
output: 'hybrid',
1111
integrations: [solid(), tailwind()],
1212
experimental: {
13-
assets: true
13+
assets: true,
14+
redirects: true,
1415
},
1516
adapter: netlify(),
1617
vite: {
@@ -19,5 +20,9 @@ export default defineConfig({
1920
compiler: 'solid'
2021
})
2122
]
23+
},
24+
redirects: {
25+
'/docs/api': '/docs',
26+
'/docs/guides': '/docs',
2227
}
2328
});

‎package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
"prism": "^4.1.2",
3535
"solid-js": "^1.7.6",
3636
"tailwindcss": "^3.0.24",
37+
"typedoc-json-parser": "^8.2.0",
3738
"unplugin-icons": "^0.16.3"
3839
},
3940
"devDependencies": {

‎src/assets/styles/pages/markdown.css

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/* Fixes tailwind not styling anything */
2+
.md h1, .md h2, .md h3, .md h4, .md h5, .md h6 {
3+
font-size: revert;
4+
font-weight: revert;
5+
}
6+
7+
.md a {
8+
color: #3182ce;
9+
}
10+
11+
.md blockquote {
12+
margin-left: 1em;
13+
border-left-color: forestgreen;
14+
border-left-style: solid;
15+
border-left-width: .1em;
16+
padding-left: 0.5em;
17+
}

‎src/components/Docs/Docs.tsx

Lines changed: 15 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,47 @@
1+
import type { ProjectParser } from "typedoc-json-parser";
12
import JSONDisplay from "./JSONDisplay";
23
import RenderProp from "./RenderProp";
4+
import RenderMethod from "./RenderMethod";
5+
import RenderConstructor from "./RenderConstructor";
36

4-
const blacklist = {
5-
classes: ["JoshError"],
6-
props: ["Josh.middlewares", "Josh.provider", "Josh.providerDataFailedError"],
7-
};
8-
9-
export default function Docs({ data }: { data: unknown }) {
7+
export default function Docs({ data }: { data: ProjectParser }) {
108
return (
119
<>
1210
<h2 class="dark:text-gray-300 my-7 text-xl">
1311
{data.name} v{data.version}
1412
</h2>
1513
{data.classes
16-
.filter((c: unknown) => !blacklist.classes.includes(c.name))
17-
.map((c: any) => (
14+
.map((c) => (
1815
<>
1916
{/* Constructor */}
20-
<RenderProp
21-
data={{
22-
name: `new ${c.name}`,
23-
parameters: c.construct.parameters,
24-
description:
25-
c.construct.comment?.description || c.comment?.description,
26-
blockTags: c.construct.comment?.blockTags?.length
27-
? c.construct.comment?.blockTags
28-
: c.comment?.blockTags,
29-
}}
17+
<RenderConstructor
18+
data={c}
3019
/>
3120
{/* Props */}
3221
{c.properties
33-
.filter((p) => !blacklist.props.includes(`${c.name}.${p.name}`))
3422
.map((p: any) => (
3523
<>
3624
<RenderProp
37-
data={{
38-
name: p.name,
39-
parameters: null,
40-
description: p.comment?.description,
41-
blockTags: p.comment?.blockTags,
42-
}}
25+
data={p}
4326
/>
4427
</>
4528
))}
4629
{/* Methods */}
4730
{c.methods
48-
.filter(
49-
(m: any) => !blacklist.props.includes(`${c.name}.${m.name}`)
50-
)
51-
.map((m: any) => (
31+
.map((m) => (
5232
<>
53-
<RenderProp
54-
data={{
55-
name: m.name,
56-
parameters: m.parameters,
57-
description: m.signatures?.[0]?.comment?.description,
58-
blockTags: m.signatures?.[0]?.comment?.blockTags,
59-
}}
33+
<RenderMethod
34+
data={m}
6035
/>
6136
</>
6237
))}
63-
{/* Debug Info */}
64-
<div class="mt-8 w-full sm:mt-0">{JSONDisplay(c)}</div>
6538
</>
6639
))}
67-
{/* <div class="mt-8 w-full sm:mt-0">
40+
<details class="mt-8 w-full sm:mt-0">
41+
<summary class="text-gray-500 dark:text-gray-400">Debug JSON</summary>
6842
{JSONDisplay(data)}
69-
</div> */}
43+
</details>
44+
7045
</>
7146
);
7247
}

‎src/components/Docs/Landing.tsx

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import type { ProjectParser } from "typedoc-json-parser";
2+
import Docs from "./Docs";
3+
4+
// TODO: Dynamically pull this from smth.
5+
const guides = [
6+
{
7+
title: "Getting Started",
8+
description: "Learn how to get started with Josh",
9+
link: "/docs/guides/getting-started",
10+
fancy: true,
11+
},
12+
{
13+
title: "Providers",
14+
description: "Learn how to use different providers with Josh",
15+
link: "/docs/guides/providers",
16+
},
17+
];
18+
19+
const api = [
20+
{
21+
title: "Josh Core",
22+
description: "The main thing you interact with",
23+
link: "/docs/api/core",
24+
fancy: true,
25+
},
26+
];
27+
28+
const makeButtons = (data: typeof guides) => (
29+
<div class="space-x-2">
30+
<a
31+
href={data.link}
32+
class={`transition text-white hover:opacity-80 shadow-lg dark:shadow px-6 py-4 rounded-lg inline-block bg-gradient-to-r duration-300 m-2 ${
33+
data.fancy ? "from-josh-500 to-josh-700" : "from-zinc-800 to-zinc-700"
34+
}`}
35+
>
36+
<div class="flex">{data.title}
37+
</div>
38+
<p class="text-sm">{data.description}</p>
39+
</a>
40+
</div>
41+
);
42+
43+
export default function DocsLanding() {
44+
return (
45+
<div class="flex flex-col grow h-full md:flex-row gap-x-10 gap-y-8 px-10 items-center h-full pt-4 md:pt-0 pb-10 md:pb-0">
46+
<div class="mt-10 md:w-1/2 sm:mt-0">
47+
<h1 class="text-6xl dark:text-gray-100 my-2 font-ledger">Guides</h1>
48+
{guides.map(makeButtons)}
49+
</div>
50+
<div class="mt-10 md:w-1/2 sm:mt-0">
51+
<h1 class="text-6xl dark:text-gray-100 my-2 font-ledger">Api Docs</h1>
52+
{api.map(makeButtons)}
53+
</div>
54+
</div>
55+
);
56+
}

‎src/components/Docs/Main.tsx

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
1+
import type { ProjectParser } from "typedoc-json-parser";
12
import Docs from "./Docs";
23

3-
export default function DocsMain({ data }: { data: unknown }) {
4-
return (
5-
<div class="px-10 py-4">
6-
<div class="mt-10 sm:mt-0">
7-
<h1 class="text-6xl dark:text-gray-100 my-2 font-ledger">
8-
Documentation
9-
</h1>
10-
<Docs data={data} />
11-
</div>
12-
</div>
13-
);
4+
export default function DocsMain({ data }: { data: ProjectParser }) {
5+
return (
6+
<div class="px-10 py-4">
7+
<div class="mt-10 sm:mt-0">
8+
<h1 class="text-6xl dark:text-gray-100 my-2 font-ledger">
9+
Documentation
10+
</h1>
11+
<Docs data={data} />
12+
</div>
13+
</div>
14+
);
1415
}

‎src/components/Docs/RenderBlockquote.tsx

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import CoreCode from "../Core/Code";
22

33
const codeBlockRegex = /^\s*```(\w+)?\n((?:.|\n)*)\n```\s*$/;
44

5+
// TODO: parse links in returns and see
56
export default function RenderBlockquote({ data }: { data: { name: string, text: string } }) {
67
switch (data.name) {
78
case "see":
@@ -23,14 +24,22 @@ export default function RenderBlockquote({ data }: { data: { name: string, text:
2324
</>);
2425
case "example":
2526
const [,lang = "js", code] = codeBlockRegex.exec(data.text) || [];
27+
if(!code) return (<></>);
2628
return (
2729
<>
2830
<h3 class="dark:text-gray-300 my-3 text-lg">
2931
Example
3032
</h3>
3133
<CoreCode text={code} language={lang} />
3234
</>);
33-
35+
case "returns":
36+
return (
37+
<>
38+
<h3 class="dark:text-gray-300 my-3 text-lg">
39+
Returns
40+
</h3>
41+
{<p class="mb-5">{data.text}</p>}
42+
</>);
3443
default:
3544
console.log("Unknown prop", data);
3645
return (<></>);

‎src/components/Docs/RenderConstructor.tsx

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import type {
2+
ClassParser,
3+
MethodParser,
4+
SignatureParser,
5+
} from "typedoc-json-parser";
6+
import JSONDisplay from "./JSONDisplay";
7+
import RenderBlockquote from "./RenderBlockquote";
8+
9+
export default function RenderConstructor({
10+
data,
11+
}: {
12+
data: ClassParser;
13+
}) {
14+
return (
15+
<div class="mb-5">
16+
<h3 class="dark:text-gray-300 my-7 text-lg">
17+
{`new ${data.name}`}
18+
{`(${data.construct.parameters.map((p) => p.name).join(", ")})`}
19+
</h3>
20+
{data.comment.description && (
21+
<p class="mb-5">{data.comment.description}</p>
22+
)}
23+
{data.comment.blockTags?.map((tag) => (
24+
<RenderBlockquote data={tag} />
25+
)) || []}
26+
{/* <div class="mt-8 w-full sm:mt-0">
27+
Debug Data:
28+
{JSONDisplay(data)}
29+
</div> */}
30+
</div>
31+
);
32+
}

‎src/components/Docs/RenderMethod.tsx

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import type {
2+
ClassParser,
3+
MethodParser,
4+
SignatureParser,
5+
} from "typedoc-json-parser";
6+
import JSONDisplay from "./JSONDisplay";
7+
import RenderBlockquote from "./RenderBlockquote";
8+
9+
export default function RenderMethod({
10+
data,
11+
signature,
12+
constructorHint,
13+
}: {
14+
data: MethodParser;
15+
signature?: SignatureParser;
16+
constructorHint?: ClassParser;
17+
}) {
18+
if (!signature && !data.signatures?.[0]) return (JSONDisplay(data));
19+
const shouldRecurse = !signature;
20+
if (!signature) signature = data.signatures[0]!;
21+
return (
22+
<div class="mb-5">
23+
<h3 class="dark:text-gray-300 my-7 text-lg">
24+
{constructorHint ? `new ${constructorHint.name}` : signature.name}
25+
{ `(${signature.parameters.map((p) => p.name).join(", ")})`}
26+
</h3>
27+
{signature.comment.description && (
28+
<p class="mb-5">{signature.comment.description}</p>
29+
)}
30+
{signature.comment.blockTags?.map((tag) => (
31+
<RenderBlockquote data={tag} />
32+
)) || []}
33+
{shouldRecurse &&
34+
(data.signatures.length > 1 ? (
35+
<>
36+
<details class="mt-8 w-full sm:mt-0">
37+
<summary>All {data.signatures.length} Signatures</summary>
38+
{data.signatures.map((s) => (
39+
<RenderMethod data={data} signature={s} />
40+
))}
41+
</details>
42+
</>
43+
) : null)}
44+
45+
{/* <div class="mt-8 w-full sm:mt-0">
46+
Debug Data:
47+
{JSONDisplay(data)}
48+
</div> */}
49+
</div>
50+
);
51+
}

‎src/components/Docs/RenderProp.tsx

Lines changed: 14 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,19 @@
1-
import JSONDisplay from './JSONDisplay';
1+
import type { PropertyParser } from 'typedoc-json-parser';
22
import RenderBlockquote from './RenderBlockquote';
33

4-
interface displayProp {
5-
name: string;
6-
description: string | null;
7-
parameters: [
8-
{
9-
name: string;
10-
description: string;
11-
type: string;
12-
required: boolean;
13-
}
14-
] | null; // Null for property, empty array for method
15-
blockTags: { name: string, text: string }[] | null;
16-
}
174

18-
export default function RenderProp({ data }: { data: displayProp }) {
5+
export default function RenderProp({ data }: { data: PropertyParser }) {
6+
if(data.name === 'constructor') console.log(data)
197
return (
20-
<div class="mb-5">
21-
<h3 class="dark:text-gray-300 my-7 text-lg">
22-
{data.name}{data.parameters ? `(${data.parameters.map((p) => p.name).join(", ")})` : ""}
23-
</h3>
24-
{data.description && <p class="mb-5">{data.description}</p>}
25-
{data.blockTags?.map((tag) =>
26-
<RenderBlockquote data={tag} />
27-
) || []}
28-
{/* <div class="mt-8 w-full sm:mt-0">
29-
Debug Data:
30-
{JSONDisplay(data)}
31-
</div> */}
32-
</div>
33-
);
8+
<div class="mb-5">
9+
<h3 class="dark:text-gray-300 my-7 text-lg">
10+
{data.name}
11+
</h3>
12+
{data.comment.description && (
13+
<p class="mb-5">{data.comment.description}</p>
14+
)}
15+
{data.comment.blockTags?.map((tag) => <RenderBlockquote data={tag} />) ||
16+
[]}
17+
</div>
18+
);
3419
}

‎src/layouts/guide.astro

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
import DefaultLayout from "./default.astro";
3+
4+
import "../assets/styles/pages/markdown.css";
5+
6+
const {frontmatter} = Astro.props;
7+
---
8+
9+
<DefaultLayout class="min-h-screen" title={frontmatter.title}>
10+
<div class="px-10 py-4">
11+
<div class="mt-10 sm:mt-0 md">
12+
<slot />
13+
</div>
14+
</div>
15+
</DefaultLayout>

0 commit comments

Comments
 (0)