feat(docs): fumadocs site for deepgym/docs

.github/workflows/deepgym-ci.yml

@@ -104,6 +104,27 @@ jobs:
       - name: Build static export
         run: bun run build
 
+  docs-site:
+    name: Docs site (lint, build, link check)
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    defaults:
+      run:
+        working-directory: deepgym/docs-site
+
+    steps:
+      - uses: useblacksmith/checkout@v1
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint (biome)
+        run: bun run lint
+
+      - name: Build static export and check links
+        run: bun run build
+
   publish:
     name: Publish DeepGym to PyPI
     runs-on: ubuntu-latest

deepgym/docs-site/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.next/
+.source/
+out/
+next-env.d.ts
+*.tsbuildinfo

deepgym/docs-site/app/[[...slug]]/page.tsx

@@ -0,0 +1,39 @@
+import { DocsBody, DocsPage } from 'fumadocs-ui/layouts/docs/page';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import type { ComponentProps } from 'react';
+import { source } from '@/lib/source';
+
+export default async function Page(props: PageProps<'/[[...slug]]'>) {
+  const page = source.getPage((await props.params).slug);
+  if (!page) notFound();
+  const MDX = page.data.body;
+
+  // The docs link to each other as on GitHub (`sessions.md`, `../traces.md`). Fumadocs resolves
+  // only hrefs that start with `./` or `../`, so a bare relative path gets `./` first.
+  const a = ({ href, ...rest }: ComponentProps<'a'>) => {
+    const relative = href && !/^([a-z][a-z\d+.-]*:|[/#.])/i.test(href) ? `./${href}` : href;
+    return <defaultMdxComponents.a href={relative && source.resolveHref(relative, page)} {...rest} />;
+  };
+
+  // The markdown's own `# ` heading is the page title, so there is no DocsTitle and the
+  // table of contents starts below it.
+  return (
+    <DocsPage toc={page.data.toc.filter((item) => item.depth > 1)}>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents, a }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: PageProps<'/[[...slug]]'>): Promise<Metadata> {
+  const page = source.getPage((await props.params).slug);
+  if (!page) notFound();
+  return { title: page.data.title };
+}

deepgym/docs-site/app/api/search/route.ts

@@ -0,0 +1,8 @@
+import { createFromSource } from 'fumadocs-core/search/server';
+import { source } from '@/lib/source';
+
+export const revalidate = false;
+
+export const { staticGET: GET } = createFromSource(source, {
+  language: 'english',
+});

deepgym/docs-site/app/global.css

@@ -0,0 +1,12 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';
+
+html {
+  scrollbar-gutter: stable;
+}
+
+html > body[data-scroll-locked] {
+  margin-right: 0px !important;
+  --removed-body-scroll-bar-size: 0px !important;
+}

deepgym/docs-site/app/layout.tsx

@@ -0,0 +1,29 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import type { ReactNode } from 'react';
+import { Provider } from '@/components/provider';
+import { source } from '@/lib/source';
+import './global.css';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata: Metadata = { title: { default: 'DeepGym', template: '%s | DeepGym' } };
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className={inter.className} suppressHydrationWarning>
+      <body className="flex flex-col min-h-screen">
+        <Provider>
+          <DocsLayout
+            tree={source.getPageTree()}
+            nav={{ title: 'DeepGym' }}
+            githubUrl="https://github.com/DeepGym/deepgym"
+          >
+            {children}
+          </DocsLayout>
+        </Provider>
+      </body>
+    </html>
+  );
+}

deepgym/docs-site/app/rl-primer.html/route.ts

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises';
+
+export const dynamic = 'force-static';
+
+// Serves deepgym/docs/rl-primer.html as is, so the site has no copy of it.
+export async function GET() {
+  const html = await readFile(`${process.cwd()}/../docs/rl-primer.html`);
+  return new Response(html, { headers: { 'Content-Type': 'text/html; charset=utf-8' } });
+}

deepgym/docs-site/biome.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "files": {
+    "includes": ["**", "!**/.next", "!**/.source", "!**/out", "!**/node_modules", "!next-env.d.ts"]
+  },
+  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 110 },
+  "javascript": { "formatter": { "quoteStyle": "single", "jsxQuoteStyle": "double" } },
+  "css": { "parser": { "tailwindDirectives": true }, "formatter": { "quoteStyle": "single" } },
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "linter": { "rules": { "preset": "recommended" } }
+}