IS-11008: simplify folder structure and gitignore

Author: aleixsuau

src/haapi-react-sdk/docs/.gitignore

@@ -5,15 +5,9 @@
 /build
 /.docusaurus
 
-# Generated by scripts/build-sandpack-sdk.mjs (npm run docs:gen)
+# Generated Sandpack/example data (npm run docs:gen)
 /src/generated/
-/docs/_overview.mdx
 
-# Generated by scripts/split-docs.mjs (npm run docs:split): one short page per `##` section
-/docs/overview/
-
-# Generated by scripts/emit-api-reference.mjs (npm run docs:apiref) from api-reference.entries.mjs
-/docs/api-reference/
-
-# Generated by scripts/emit-examples.mjs (npm run docs:examples) from examples.entries.mjs
-/docs/examples/
+# The entire Docusaurus content tree is generated (build-sandpack-sdk → split-docs →
+# emit-api-reference → emit-examples) from the SDK README, examples/*.tsx and TSDoc.
+/content/

src/haapi-react-sdk/docs/README.md

@@ -1,7 +1,8 @@
 # HAAPI React SDK docs
 
-Docusaurus site for the HAAPI React SDK. Most content is **generated** from the SDK source, so you rarely
-edit pages by hand — you edit the SDK (README + TSDoc) and the example files, and the build assembles the site.
+Docusaurus site for the HAAPI React SDK. Almost all content is **generated** from the SDK source: you
+edit the SDK (`README.md` + component TSDoc) and the example files, and the build assembles the site.
+You rarely touch pages by hand.
 
 ## Run it
 
@@ -11,49 +12,33 @@ npm run docs:build    # production build (fails on broken links)
 ```
 
 Both run the generators first (`predocs`): `docs:gen → docs:split → docs:apiref → docs:examples`.
+Everything they emit lands in **`content/`**, which is gitignored — never edit it, change the source.
 
 ## Where content comes from
 
 | Sidebar section | Source | How |
 |---|---|---|
-| **Overview** | SDK `README.md` | `docs:gen` → `_overview.mdx`, `docs:split` → one page per `##` |
-| **API Reference** | component **TSDoc** | `docs:apiref` extracts the TSDoc (`scripts/extract-tsdoc.mjs`) and emits a Markdown page per entry in `api-reference.entries.mjs` |
+| **Overview** | SDK `README.md` | `docs:gen` → `content/_overview.mdx`, `docs:split` → one page per `##` |
+| **API Reference** | component **TSDoc** | `docs:apiref` extracts the TSDoc and emits a Markdown page per entry in `api-reference.entries.mjs` |
 | **Examples** | `examples/*.tsx` | `docs:examples` emits a playground page per entry in `examples.entries.mjs` |
 
-Generated folders (`docs/_overview.mdx`, `docs/overview/`, `docs/api-reference/`, `docs/examples/`) are
-**gitignored** — don't edit them; change the source instead.
+## Examples are live playgrounds
 
-## Examples = live playgrounds
+Each `examples/<Name>.tsx` is a self-contained app (a default `App` wrapped in `<ExamplePreviewer>`) that
+runs **live** in the docs against a mocked HAAPI backend — readers can edit the code and see it update.
 
-An example is a self-contained `examples/<Name>.tsx` (default `App`, wrapped in `<ExamplePreviewer>`).
-`docs:gen` bundles every example into `examples.json` (keyed by basename). You reference it by **name**
-(its filename, no `.tsx`) in one of two ways — both get rewritten, at generation time, into the same
-`<DocExample id="<Name>" />` runtime tag, which looks the source up in `examples.json` by that `id`:
+To show an example on a page, reference its file in any of these ways:
 
-- **A markdown link to the file** — `[label](…/examples/<Name>.tsx)`, in the SDK `README.md` (→ Overview).
-  It stays a clickable link on GitHub; the build derives `<Name>` from the link and converts it to a
-  playground (`build-sandpack-sdk.mjs`).
-- **A `{@see_example docs/examples/<Name>.tsx Label}` marker** — inside a component's TSDoc, so the
-  playground renders inline on its API Reference page (`emit-api-reference.mjs`).
-
-(The Examples section pages are emitted from `examples.entries.mjs`. You don't hand-write `<DocExample>` —
-it's the generated tag underlying all of these.) Each mounts the example in Sandpack against the **mocked**
-HAAPI driver (no backend) using the shared closure in `src/sandpack/closure.ts`.
-
-```
-examples/<Name>.tsx ──(docs:gen)──▶ examples.json[<Name>]
-        │
-        ├─ [label](…/examples/<Name>.tsx)   (README markdown)  ─┐
-        ├─ {@see_example …<Name>.tsx Label}  (component TSDoc)  ─┤─(generate)─▶ <DocExample id="<Name>"/>
-        └─ entry in examples.entries.mjs     (Examples section) ─┘                        │
-        ▼                                                                                 ▼
-   examples.json[<Name>] ──▶ SandpackPlayer( SDK + mocked driver + <Name>.tsx )  ──▶  live playground
-```
+- **A markdown link** in the SDK `README.md` — `[label](…/examples/<Name>.tsx)`. Renders as a playground
+  on the Overview section, and stays a normal clickable link on GitHub.
+- **A `{@see_example docs/examples/<Name>.tsx Label}` marker** in a component's TSDoc — renders the
+  playground inline on that component's API Reference page.
+- **An entry in `examples.entries.mjs`** — gives the example its own page in the Examples section.
 
 ## Add an example
 
 1. Create `examples/MyExample.tsx` — a default `App`, wrapped in `<ExamplePreviewer>`.
-2. Surface it by **name**: a markdown link `[label](…/examples/MyExample.tsx)` in the README, **or** an
-   entry in `examples.entries.mjs` (Examples section), **or** a `{@see_example …MyExample.tsx Label}`
-   marker in a component's TSDoc.
-3. `npm run docs` — it's picked up automatically; no registry edit needed for `examples.json`.
+2. Reference it one of the three ways above (markdown link, `{@see_example}` marker, or an
+   `examples.entries.mjs` entry).
+3. `npm run docs` — it's picked up automatically.
+

src/haapi-react-sdk/docs/docusaurus.config.ts

@@ -38,6 +38,9 @@ const config: Config = {
       'classic',
       {
         docs: {
+          // `content/` is fully generated (build-sandpack-sdk, split-docs, emit-api-reference,
+          // emit-examples) — kept out of the default `docs/` to avoid a confusing `docs/docs` nesting.
+          path: 'content',
           routeBasePath: '/',
           sidebarPath: './sidebars.ts',
         },

…react-sdk/docs/api-reference.entries.mjs …k/docs/scripts/api-reference.entries.mjssrc/haapi-react-sdk/docs/api-reference.entries.mjs renamed to src/haapi-react-sdk/docs/scripts/api-reference.entries.mjs src/haapi-react-sdk/docs/api-reference.entries.mjs renamed to src/haapi-react-sdk/docs/scripts/api-reference.entries.mjs

@@ -60,8 +60,8 @@ const catalogOutFile = join(scriptDir, '../src/generated/catalog.json');
 // The SDK's own README, surfaced as the docs landing/first page (as MDX, so `{@see_example}` markers
 // can become live `<DocExample>` playgrounds). Front matter is prepended — single source of truth.
 const readmeFile = join(sdkRoot, 'README.md');
-// Underscore prefix → Docusaurus ignores this long source; `split-docs.mjs` splits it into `docs/overview/`.
-const readmeOutFile = join(scriptDir, '../docs/_overview.mdx');
+// Underscore prefix → Docusaurus ignores this long source; `split-docs.mjs` splits it into `content/overview/`.
+const readmeOutFile = join(scriptDir, '../content/_overview.mdx');
 
 // Every docs example file (examples/*.tsx) as { <basename>: <source> }, so MDX pages (the
 // README/overview) can mount any of them as a live playground via `<DocExample id="…">`, and the closure

src/haapi-react-sdk/docs/scripts/build-sandpack-sdk.mjs

@@ -10,7 +10,7 @@
  */
 
 /*
- * Generates the API Reference docs tree (`docs/api-reference/**`) from the single layout declaration in
+ * Generates the API Reference docs tree (`content/api-reference/**`) from the single layout declaration in
  * `api-reference.entries.mjs`. Each leaf entry → one MDX page whose body is the export's TSDoc, extracted
  * here and written as real Markdown (+ `<DocExample>` playgrounds); each group → a subfolder with its own
  * `_category_.json`. `sidebar_position` follows declaration order.
@@ -29,7 +29,7 @@ import { apiReferenceStructure, isApiReferenceGroup } from '../api-reference.ent
 import { extractDocBlocks, blocksToMdx, hasExamples } from './extract-tsdoc.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DOCS_DIR = path.resolve(SCRIPT_DIR, '../docs');
+const DOCS_DIR = path.resolve(SCRIPT_DIR, '../content');
 const OUT_DIR = path.join(DOCS_DIR, 'api-reference');
 // The SDK package root, where entry `file` paths (`haapi-stepper/<file>`) are resolved from.
 const SDK_ROOT = path.resolve(SCRIPT_DIR, '../..');
@@ -121,4 +121,4 @@ writeCategory(OUT_DIR, 'API Reference', 2);
 const pages = emitItems(apiReferenceStructure, OUT_DIR);
 
 // eslint-disable-next-line no-console
-console.log(`[emit-api-reference] wrote ${pages} pages to docs/api-reference/`);
+console.log(`[emit-api-reference] wrote ${pages} pages to content/api-reference/`);

src/haapi-react-sdk/docs/scripts/emit-api-reference.mjs

@@ -10,7 +10,7 @@
  */
 
 /*
- * Generates the "Examples" docs section (`docs/examples/**`) from the single layout declaration in
+ * Generates the "Examples" docs section (`content/examples/**`) from the single layout declaration in
  * `examples.entries.mjs`. Each leaf → one short MDX shell that mounts `<DocExample id=…/>` (a live
  * Sandpack playground for `examples/<id>.tsx`); each group → a subfolder with its own
  * `_category_.json`. `sidebar_position` follows declaration order.
@@ -24,7 +24,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { examplesStructure, isExamplesGroup } from '../examples.entries.mjs';
 
-const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../docs');
+const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../content');
 const OUT_DIR = path.join(DOCS_DIR, 'examples');
 const GENERATED_NOTE = '{/* AUTO-GENERATED by scripts/emit-examples.mjs from examples.entries.mjs — do not edit. */}';
 const DOC_EXAMPLE_IMPORT = "import DocExample from '@site/src/components/DocExample';";
@@ -75,4 +75,4 @@ writeCategory(OUT_DIR, 'Examples', 3);
 const pages = emitItems(examplesStructure, OUT_DIR);
 
 // eslint-disable-next-line no-console
-console.log(`[emit-examples] wrote ${pages} pages to docs/examples/`);
+console.log(`[emit-examples] wrote ${pages} pages to content/examples/`);

src/haapi-react-sdk/docs/scripts/emit-examples.mjs

@@ -15,7 +15,7 @@
  * `{@see_example <path> <label>}` markers) — and renders them to MDX: prose verbatim, each marker as a
  * `<DocExample id=… />` (resolved at runtime from the generated examples map) in the snippet's place.
  *
- * `emit-api-reference.mjs` writes the result straight into `docs/api-reference/**`, so the pages are
+ * `emit-api-reference.mjs` writes the result straight into `content/api-reference/**`, so the pages are
  * real Markdown — Docusaurus builds the right-hand table of contents and heading anchors natively.
  */
 

…aapi-react-sdk/docs/examples.entries.mjs …ct-sdk/docs/scripts/examples.entries.mjssrc/haapi-react-sdk/docs/examples.entries.mjs renamed to src/haapi-react-sdk/docs/scripts/examples.entries.mjs src/haapi-react-sdk/docs/examples.entries.mjs renamed to src/haapi-react-sdk/docs/scripts/examples.entries.mjs

@@ -23,7 +23,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import GithubSlugger from 'github-slugger';
 
-const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../docs');
+const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../content');
 const GENERATED_NOTE = '{/* AUTO-GENERATED by scripts/split-docs.mjs from the sibling _<name>.mdx — do not edit. */}';
 
 /** Split `---\n…\n---` frontmatter off the top → `{ data, body }` (values kept as raw strings). */
@@ -171,5 +171,5 @@ const sources = fs.readdirSync(DOCS_DIR).filter(f => /^_.+\.mdx?$/.test(f));
 for (const source of sources) {
   const { name, sections } = splitFile(path.join(DOCS_DIR, source));
   // eslint-disable-next-line no-console
-  console.log(`[split-docs] ${source} → docs/${name}/ (index + ${sections} sections)`);
+  console.log(`[split-docs] ${source} → content/${name}/ (index + ${sections} sections)`);
 }