chore(docs): add improvements (#119)

Co-authored-by: DominicGBauer <[email protected]>

Author: DominicGBauer

docs/docusaurus.config.ts

@@ -1,7 +1,9 @@
 import { themes as prismThemes } from 'prism-react-renderer';
+import type { TypeDocOptionMap } from 'typedoc';
 import type { Config } from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
-import { packageMap } from './utils/packageMap';
+import type { PluginOptions } from 'docusaurus-plugin-typedoc';
+import { DOC_FOLDER, packageMap } from './utils/packageMap';
 import 'dotenv/config';
 
 const PROJECT_NAME = process.env.GH_PROJECT_NAME;
@@ -13,8 +15,17 @@ const plugins = Object.entries(packageMap).map(([id, config]) => [
     excludeExternals: true,
     entryPoints: config.entryPoints,
     tsconfig: config.tsconfig,
-    out: config.dirName
-  }
+    out: `${DOC_FOLDER}/${config.dirName}`,
+    parametersFormat: 'table',
+    propertiesFormat: 'table',
+    enumMembersFormat: 'table',
+    indexFormat: 'table',
+    typeDeclarationFormat: 'table',
+    membersWithOwnFile: ['Class', 'Enum', 'Function', 'Interface'],
+    textContentMappings: {
+      'title.memberPage': '{name}'
+    }
+  } as Partial<PluginOptions | TypeDocOptionMap>
 ]);
 
 const config: Config = {
@@ -45,7 +56,6 @@ const config: Config = {
     defaultLocale: 'en',
     locales: ['en']
   },
-
   presets: [
     [
       'classic',

docs/package.json

@@ -24,9 +24,9 @@
     "@docusaurus/tsconfig": "3.2.1",
     "@docusaurus/types": "3.2.1",
     "@types/node": "^20.12.5",
-    "docusaurus-plugin-typedoc": "^0.22.0",
-    "typedoc": "^0.25.12",
-    "typedoc-plugin-markdown": "^3.17.1",
+    "docusaurus-plugin-typedoc": "^1.0.0next.28",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^4.0.0next.55",
     "typescript": "~5.4.4"
   },
   "browserslist": {

docs/sidebars.ts

@@ -1,15 +1,14 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
-import { packageMap } from './utils/packageMap';
+import { DOC_FOLDER, packageMap } from './utils/packageMap';
 
 const items = Object.values(packageMap).map((config) => ({
   type: 'category',
   label: config.name,
-  items: [
-    {
-      type: 'autogenerated',
-      dirName: config.dirName
-    }
-  ]
+  link: {
+    type: 'doc',
+    id: `${config.dirName}/index`
+  },
+  items: require(`./${DOC_FOLDER}/${config.dirName}/typedoc-sidebar.cjs`)
 })) as unknown as SidebarsConfig;
 
 const sidebars: SidebarsConfig = {

docs/utils/packageMap.ts

@@ -1,3 +1,5 @@
+export const DOC_FOLDER = 'docs';
+
 enum Packages {
   ReactNativeSdk = 'react-native-sdk',
   ReactSdk = 'react-sdk',

packages/powersync-react/src/hooks/PowerSyncContext.ts

@@ -2,4 +2,21 @@ import { AbstractPowerSyncDatabase } from '@journeyapps/powersync-sdk-common';
 import React from 'react';
 
 export const PowerSyncContext = React.createContext<AbstractPowerSyncDatabase | null>(null);
+/**
+ * Custom hook that provides access to the PowerSync context.
+ * @returns The PowerSync Database instance.
+ * @example
+ * const Component = () => {
+ *   const db = usePowerSync();
+ *   const [lists, setLists] = React.useState([]);
+ *
+ *   React.useEffect(() => {
+ *     powersync.getAll('SELECT * from lists').then(setLists)
+ *   }, []);
+ *
+ *   return <ul>
+ *     {lists.map(list => <li key={list.id}>{list.name}</li>)}
+ *   </ul>
+ * };
+ */
 export const usePowerSync = () => React.useContext(PowerSyncContext);

packages/powersync-react/src/hooks/usePowerSyncWatchedQuery.ts

@@ -4,6 +4,16 @@ import { usePowerSync } from './PowerSyncContext';
 
 /**
  * A hook to access the results of a watched query.
+ * @example
+ * export const Component = () => {
+ * const lists = usePowerSyncWatchedQuery('SELECT * from lists');
+ *
+ * return <View>
+ *   {lists.map((l) => (
+ *     <Text key={l.id}>{JSON.stringify(l)}</Text>
+ *   ))}
+ * </View>
+ * }
  */
 export const usePowerSyncWatchedQuery = <T = any>(
   sqlStatement: string,