chore: improve API docs structure with dedicated index.md files

docs-viewer/README.md

@@ -2,9 +2,31 @@
 
 ## docs.warp-drive.io
 
-### Previewing
+### Development
 
-From this root directory, run `pnpm preview`
+For development with auto-rebuild and hot reload:
+
+```bash
+pnpm start
+```
+
+This will:
+
+- Watch for changes in all package `src/` directories and `guides/` directory
+- Automatically rebuild API docs when files change
+- Run VitePress dev server with hot module replacement
+
+### Static Preview
+
+To preview the built site without auto-rebuild:
+
+```bash
+# First build the site
+pnpm build
+
+# Then preview it locally
+pnpm preview
+```
 
 ### Deploying
 
@@ -39,4 +61,3 @@ This must be run manually after any changes to api documentation for them to be
 available to a running instance of the api docs application. If the app is not
 currently running, this command is unneeded as `preview-api-docs` will also do
 an initial build of the docs.
-

docs-viewer/docs.warp-drive.io/.vitepress/config.mts

@@ -178,17 +178,20 @@ export default withPwa(
         {
           text: 'API Docs',
           collapsed: true,
-          // link: '/api/',
+          // Ensures that this sidebar item is active when you load /api/ or any of its sub-pages
+          link: '/api/',
           items: [
-            { text: 'Universal' },
+            { text: 'Universal Packages' },
             ...TypeDocSidebar.corePackages.items,
-            { text: 'Frameworks' },
+            { text: 'Framework Packages' },
             ...TypeDocSidebar.frameworkPackages.items,
           ],
         },
         {
-          text: 'Legacy Packages',
+          text: 'Legacy API Docs',
           collapsed: true,
+          // If you uncomment this, it makes the Legacy API Docs sidebar state mirror the API Docs sidebar state,
+          // which feels super weird.
           // link: '/api/',
           items: TypeDocSidebar.oldPackages,
         },

docs-viewer/docs.warp-drive.io/.vitepress/theme/custom.css

@@ -6,7 +6,7 @@ html:not(.dark) .dark-only {
   display: none !important;
 }
 
-.VPSidebarItem .level-1 > .item > p.text {
+.VPSidebarItem.level-1 > .item > p.text {
   font-weight: 600;
   color: var(--vp-c-text-1);
 }

docs-viewer/src/site-utils.ts

@@ -435,7 +435,7 @@ export async function postProcessApiDocs() {
   }
 
   // generate the API documentation
-  const apiDocumentation = `${ApiDocumentation}\n\n## Main Packages\n\n${MainPackages.join('\n')}\n\n## Framework Packages\n\n${FrameworkPackages.join('\n')}\n\n## Legacy Packages\n\n${OldPackages.join('\n')}\n\n`;
+  const apiDocumentation = `${ApiDocumentation}\n\n## Universal Packages\n\n${MainPackages.join('\n')}\n\n## Framework Packages\n\n${FrameworkPackages.join('\n')}\n\n## Legacy Packages\n\n${OldPackages.join('\n')}\n\n`;
 
   // copy the rest of the files
   const files = globSync('**/*.md', { cwd: dir, nodir: true });
@@ -451,8 +451,9 @@ export async function postProcessApiDocs() {
 
     let newContent = content;
 
-    // if the file is in @warp-drive/legacy add the legacy badge
-    if (file.includes('@warp-drive/legacy')) {
+    // if the file is in a legacy package add the legacy badge
+    const isLegacyPackage = OLD_PACKAGES.some((pkg) => file.includes(pkg)) || file.includes('@warp-drive/legacy');
+    if (isLegacyPackage) {
       newContent = `<Badge type="danger" text="@legacy" /><br><br>` + content;
     }
 

guides/contributing/writing-documentation/index.md

@@ -6,5 +6,14 @@ categoryTitle: Writing Documentation
 
 # Writing Documentation
 
-- [Documenting APIs](./writing-api-docs.md)
-- [Writing Guides](./writing-guides.md)
+There are two sources of documentation in this repository:
+
+- [Guides](../../index.md): the manual compiled from markdown files. Find best practices in [Writing Guides](./writing-guides.md).
+
+- [API Docs](../../../api/): compiled from source code. See [Documenting APIs](./writing-api-docs.md) for more details.
+
+::: tip 💡 Great documentation requires both guides and docs.
+We encourage updating any associated guides affected by code changes as you make them, and writing new guides when appropriate.
+:::
+
+Both can be previewed by following the instructions in the [Docs Viewer](https://github.com/warp-drive-data/warp-drive/blob/main/docs-viewer/README.md).

guides/contributing/writing-documentation/writing-api-docs.md

@@ -3,33 +3,27 @@ title: Documenting APIs
 order: 1
 ---
 
-# Writing Documentation
-
-There are two sources of documentation in this repository:
-
-- [Guides](../../index.md) - markdown files that are compiled into the manual for the website
-- inline code comments and types - from which the API Docs are compiled
-
-Both are previewable by following the instructions in the [Docs Viewer](https://github.com/warp-drive-data/warp-drive/blob/main/docs-viewer/README.md)
-
-Great documentation requires both guides and docs. We encourage updating any associated guides affected by code changes as you make them, and writing new guides when appropriate.
+# Writing API Documentation
 
+Our [API Docs](../../../api/) are compiled from inline code comments and types as well as `src/index.md` files.
 
 ## API Documentation Infra Overview
 
 API Documentation is generated from [TSDoc](https://tsdoc.org/) comments in the source code
 compiled with [TypeDoc](https://typedoc.org/) and transformed for [Vitepress](https://vitepress.dev/) using [typedoc-plugin-markdown](https://www.typedoc-plugin-markdown.org/plugins/vitepress)
 
-TSDoc syntax is similar to YUIDoc and JSDoc but there are occassional nuances where it becomes best to know the underlying grammar is TSDoc
+TSDoc syntax is similar to YUIDoc and JSDoc but there are occasional nuances where it becomes best to know that the underlying grammar is TSDoc
 and parser is TypeDoc.
 
 TypeDoc is configured to follow our public package entrypoints to
 auto-discover documentation. It documents everything reachable, public or private including properties and methods that have no associated
-code docs. It uses typescript to understand the source-code and builds documentation from the combination of Type signatures and TSDoc comments.
+code docs. It uses typescript to understand the source-code and builds documentation from the combination of Type signatures and TSDoc comments. This is great, but it means that its very easy to leak private APIs
+into the docs.
 
-This is great, but it means that its very easy to leak private APIs
-into the docs. Use `/** @internal */` on things that should not be
+::: warning Avoid leaking private APIs into the public docs!
+Use `/** @internal */` on things that should not be
 put into the public docs.
+:::
 
 While API Documentation lives with the source-code, the code itself plays no part in the documentation
 that is generated: everything is compiled from comments alone.
@@ -39,10 +33,6 @@ nuances and syntaxes to know, as well as how to test and preview the doc comment
 
 <br>
 
----
-
-<br>
-
 ## Documentation Syntax
 
 <br>
@@ -129,7 +119,7 @@ for fellow developers that shouldn't be exposed to end consumers.
 /**
  * This is a private utility for updating the state
  * of a relationship.
- * 
+ *
  * @internal
  */
 function somethingInside() {}
@@ -158,15 +148,15 @@ For instance
 ```ts
 /**
  * ## Overview
- * 
+ *
  * Some details
- * 
+ *
  * ### An Example
- * 
+ *
  * ```ts
  * new Store();
  * ```
- * 
+ *
  * @public
  */
 ```
@@ -179,15 +169,15 @@ This means we can do code examples that toggle between files or formats.
 ```ts
 /**
  * ::: code-group
- * 
+ *
  * ```ts [example.ts]
  * export function numberFromStrong(str: string): number {}
  * ```
- * 
+ *
  * ```js [example.js]
  * export function numberFromStrong(str) {}
  * ```
- * 
+ *
  * :::
  */
 ```
@@ -210,17 +200,17 @@ and some documentation may be unexpectedly truncated.
 ```ts
 /**
  * ## Overview
- * 
+ *
  * Some details
- * 
+ *
  * ### An Example
- * 
+ *
  * ```ts
  * class User extends Model {
  *   @attr name;
  * }
  * ```
- * 
+ *
  * @public
  */
 ```
@@ -230,17 +220,17 @@ and some documentation may be unexpectedly truncated.
 ```ts
 /**
  ## Overview
- 
+
  Some details
- 
+
  ### An Example
- 
+
  \```ts
  class User extends Model {
    @attr name;
  }
  \```
- 
+
  @public
 */
 ```
@@ -256,16 +246,13 @@ we would do the following in `packages/core-types/src/index.ts`
 /**
  * This package provides essential types and symbols used
  * by all the other WarpDrive packages.
- * 
+ *
  * @module
  */
 ```
 
-<br>
-
 ### Always specify `@since` on non-type public APIs
 
-
 ```ts
 /**
  * @since 1.13.0
@@ -295,20 +282,14 @@ be used to give a meaningful description only.
 ```ts
 /**
  * Adds two numbers
- * 
+ *
  * @param a - the first number to add
  * @param b - the second number to add
  * @return the sum of the two numbers
  */
 function add(a: number, b: number): number {}
 ```
 
-<br>
-
----
-
-<br>
-
 ## Documentation Hygiene
 
 <br>
@@ -342,7 +323,7 @@ From inside the `docs-viewer` directory
 > migrate to tsdoc and typedoc. Once the migration is nearing
 > completion we will create a transform to restore these docs.
 
-Run `bun preview-api-docs` from the project root or the `docs-viewer` directory. 
+Run `bun preview-api-docs` from the project root or the `docs-viewer` directory.
 
 This will build and run the (external) api-docs app with the current state of the api docs in the repo.
 

guides/contributing/writing-documentation/writing-guides.md

@@ -3,9 +3,13 @@ title: Writing Guides
 order: 2
 ---
 
-# Writing Effective Guides
+# Writing Guides
 
-## 1. Know Your Audience
+The Guide to writing our [Guides](../../index.md).
+
+## Writing Effective Guides
+
+### 1. Know Your Audience
 
 ***Warp*Drive**'s Documentation has to balance appealing to many different audiences. Here are some example audiences:
 
@@ -30,9 +34,12 @@ Some examples of ways to achieve this balance:
 - Migrations is a top level section to help those category 5 users find what they are looking for faster.
 - Explicitly named legacy pages (such as [Setup - Legacy (Ember)](/guides/configuration/ember) help those users without muddying instructions for everyone else. Note: this clarity also helps decision makers, as they will like to see that when the time for change comes there are resources to help them that are easy to find and well marked - but which they don't need to know about just yet.
 
-## 2. Iterate, A Lot
+### 2. Iterate, A Lot
 
 Making great documentation requires a lot of iteration. A great way to iterate is to write documentation that someone needs, ask them to use it - and use the feedback from where they
 stumble to improve the documentation for the next person. The more iteration that happens,
 the more the docs become a source of information that works well for everyone.
 
+## Guides Infra Overview
+
+Our [Guides](../../index.md) are compiled from markdown files in `guides/` using [VitePress](https://vitepress.dev/).

guides/the-manual/data.md

@@ -20,7 +20,7 @@ Misalignment tends to occur when API and Application developers don't work toget
 requirements, or when the format in use is "lossy" (unable to accurately convey the full scope of
 information being serialized).
 
-We encourage the use of [JSON:API](https://jsonapi.org/) as the wire and cache format because unlike
+We encourage the use of [{json:api}](https://jsonapi.org/) as the wire and cache format because unlike
 most other formats in use today it encodes information about your data in a near-lossless and easily-cacheable manner.
 
 For the presentation format, we encourage applications to limit the amount of manual transformation

packages/active-record/src/index.md

@@ -1,14 +1,13 @@
 # @ember-data/active-record
 
-:::warning ⚠️ This package only exists for backwards compatibility
-Newer apps should use {@link @warp-drive/utilities! | @warp-drive/utilities}
-:::
+:::warning ⚠️ Legacy Package
+
+**This package only exists for backwards compatibility.**
 
-This package used to provide the RequestManager and its related
-facilities. The source-code has since been moved to {@link @warp-drive/utilities! | @warp-drive/utilities}
-and this package now exists solely to provide backwards compatibility.
+Newer apps should use {@link @warp-drive/utilities! | @warp-drive/utilities}.
+:::
 
----
+## Overview
 
 This package provides utilities for working with [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html#convention-over-configuration-in-active-record) APIs.
 

packages/adapter/src/index.md

@@ -1,11 +1,16 @@
 # @ember-data/adapter
 
 :::warning ⚠️ Legacy Package
+
+**This package only exists for backwards compatibility.**
+
 **Adapters are a LEGACY feature** that is no longer encouraged for new applications.
 
 **For new projects:** Use {@link @warp-drive/core!RequestManager | Handlers} with the {@link @warp-drive/core!RequestManager | RequestManager} instead.
 :::
 
+## Overview
+
 This package provides REST and [{json:api}](https://jsonapi.org) Implementations of the legacy Adapter Interface when using the older packages.
 
 **Why it's legacy:** The Adapter pattern was designed for class-based, inheritance-heavy architectures where each resource type could have its own data fetching logic. This approach:

packages/adapter/src/index.ts

@@ -1 +1,5 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 export { Adapter as default, BuildURLMixin } from '@warp-drive/legacy/adapter';

packages/adapter/typedoc.config.mjs

@@ -6,7 +6,7 @@ const config = {
   entryFileName: 'index',
   entryPoints: entryPoints.filter((entry) => !entry.includes('-private')),
   out: 'doc',
-  readme: 'none',
+  readme: 'src/index.md',
 };
 
 export default config;