Documentation for dev and copilot #4384

michaelmkraus · 2025-06-16T07:26:25Z

Proposed changes

Generate context for copilot and generate documentation for developers

closes #1349

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Refactoring (fix on existing components or architectural decisions)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation Update (if none of the other choices apply)

Further comments

…typedoc

…onding file

…ons.md

…/file filtering

…luding component documentation

…iting them completely

…copy them to component folder

…t].md

…egrate it into [component].md

mfranzke · 2025-07-17T05:14:52Z

scripts/documentation/README.md

+```jsonc
+// scripts/package.json
+"copilot:typedoc": "typedoc --options ../typedoc.json --tsconfig tsconfig.typedoc.json",


Suggested change

```jsonc

// scripts/package.json

"copilot:typedoc": "typedoc --options ../typedoc.json --tsconfig tsconfig.typedoc.json",

```bash

npm run copilot:typedoc --workspace=scripts

I'm struggling on where to put this documentation. Either at this place to have it near the script, or within docs/ folder in the root directory. The latter would ensure that it's easily discoverable in between the rest of the documentation, which might be slightly better. Afterwards we would have to change the commands within this file to bash instead of listing the scripts themselves.

mfranzke · 2025-07-17T06:44:05Z

scripts/documentation/README.md

+
+### 1.1 Annotate components and generate component Markdown
+
+Annotate your components with [JSDoc](https://jsdoc.app/) (classes, properties, etc.) so TypeDoc can pick up API signatures. Then generate the component API documentation:


This makes it pretty clear on what command to run for generating the documentation. But maybe we should add a least a sentence or two regarding how the annotation is being done exactly (without putting the pressure on the reader to go through the documentation of JSDoc), and even also provide a path to one of the documentations that we've already prepared for someone to adapt from.

I added an example showing how to annotate a component

mfranzke · 2025-07-17T06:44:20Z

scripts/documentation/README.md

+
+### 1.3 Annotate CSS variables and extract CSS docs
+
+Ensure, that all CSS variables of your component (starting with `--db-...` in the `[component].scss`) are annotated with [SassDoc](http://sassdoc.com/). Then run the script. It scans `packages/components/src/components` for subfolders (each component) and loads each component's SCSS file and transforms them into Markdown.


This makes it pretty clear on what command to run for generating the documentation. But maybe we should add a least a sentence or two regarding how the annotation is being done exactly (without putting the pressure on the reader to go through the documentation of SassDoc), and even also provide a path to one of the documentations that we've already prepared for someone to adapt from.

I added an example showing how to annotate a component

mfranzke · 2025-07-17T06:46:04Z

scripts/documentation/README.md

+
+### 1.2 Generate code examples via Mitosis
+
+Create a `*.docs.lite.tsx` file in the docs directory of the component containing examples for your component. Then run the Mitosis build to extract code snippets (React, Angular, Vue) from your `*.docs.lite.tsx` files:


While going through those examples, I was thinking about whether we could generate those out of the existing JSON data that we've set up to generate the documentation pages; those could (or even should?) be equal most of the time and we wouldn't need to do duplicate work or go out of sync or missing to update some documentation by a single source of truth.

mfranzke · 2025-07-17T06:50:41Z

scripts/documentation/README.md

+
+```jsonc
+// scripts/package.json
+"copilot:extract-css": "node documentation/extract-css-vars.js",


maybe I'm missing something here, but this command doesn't generate any CSS contents at the moment, not even for the button component, in which to my understanding some of these annotations are even already included.

I just added a commented scss file (drawer). After running the script, I get the corresponding markdown created (drawer.css.md).

nmerget · 2025-07-18T08:42:17Z

scripts/documentation/merge-component-docs.js

+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fg from 'fast-glob';


Why do we use fast-glob here? In other files we use glob

michaelmkraus added 4 commits June 12, 2025 09:39

feat(doc): add basic copilot-instructions.md and llms.txt

9db5e8b

chore(): add typedoc to project

ea41c1f

chore(): add basic adr for copilot documentation

fdfb88e

docs(): add some documentation for component to test generation with …

006ca98

…typedoc

michaelmkraus self-assigned this Jun 16, 2025

michaelmkraus added this to UX Engineering Team Backlog Jun 16, 2025

michaelmkraus added the 📕documentation Improvements or additions to documentation label Jun 16, 2025

michaelmkraus added 16 commits June 16, 2025 17:14

feat(): add postinstall script to copy copilot instruction to corresp…

5b34e33

…onding file

docs: document automated postinstall propagation of copilot-instructi…

93076c2

…ons.md

feat: add generate-copilot-instructions script with PascalCase folder…

314cd06

…/file filtering

docs: document automated generation of copilot-instructions.md by inc…

730e839

…luding component documentation

docs: adapt jsdoc for button and its models

c528673

chore: add plugin to merge typedoc files

6133886

feat: append component doc to existing instructions instead of overwr…

c11b057

…iting them completely

chore: add typedoc for doc generation

f2ad116

chore: remove comment

793a26f

feat: merge component documentations into [MyComponent].md files and …

1efbd0e

…copy them to component folder

feat: restructure script and add comments

1bc0087

chore: delete existing md files within button docs folder

a88ae59

feat: add script to generate framework-specific code snippets

e3d2125

feat: use mitosis plugin instead of script to generate examples

63d7dbd

feat: append example snippets for react, angular and vue to [componen…

fcea6f6

…t].md

feat: introduce sassdoc to generate md documentation for SCSS and int…

12367ed

…egrate it into [component].md

mfranzke changed the title ~~Documentation for dev and copilo~~ Documentation for dev and copilot Jul 4, 2025

michaelmkraus added 6 commits July 10, 2025 11:50

feat: add script to extract sassdoc and save in md

2c4f59b

chore: move scripts to documentation subfolder

1ccc328

chore: add readme describing how to generate copilot-instructions.md

14b7a17

chore: adapt readme describing how to generate copilot-instructions.md

25c54e7

feat: fix typos in readme

8d1be02

chore: adapt skript calls and readme

cd80ca1

mfranzke added the 🪩🔥🕺coolTopic some relevant topics, that we even also need to report in different rounds / to stakeholders label Jul 16, 2025

michaelmkraus added 2 commits July 16, 2025 15:13

chore: moved script calls to scripts/package.json and adapt README

e08e252

chore: moved typedoc.json to scripts folder

ce1769d

mfranzke reviewed Jul 17, 2025

View reviewed changes

michaelmkraus added 4 commits July 17, 2025 10:26

feat: add sassdoc comments to variables for drawer

c83d172

docs: add examples for SassDoc and JSDoc

7444bb4

feat: only handle defined components and skip others

c0095d9

docs: added open points to readme

65e099a

nmerget reviewed Jul 18, 2025

View reviewed changes

feat: also copy all component-md files to docs/copilot folder

5f254da

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Documentation for dev and copilot #4384

Documentation for dev and copilot #4384

michaelmkraus commented Jun 16, 2025 •

edited by nmerget

Loading

Uh oh!

mfranzke Jul 17, 2025

Uh oh!

mfranzke Jul 17, 2025

Uh oh!

michaelmkraus Jul 17, 2025

Uh oh!

mfranzke Jul 17, 2025

Uh oh!

michaelmkraus Jul 17, 2025

Uh oh!

mfranzke Jul 17, 2025

Uh oh!

mfranzke Jul 17, 2025

Uh oh!

michaelmkraus Jul 17, 2025

Uh oh!

nmerget Jul 18, 2025

Uh oh!

Uh oh!


		### 1.1 Annotate components and generate component Markdown

		Annotate your components with [JSDoc](https://jsdoc.app/) (classes, properties, etc.) so TypeDoc can pick up API signatures. Then generate the component API documentation:


		### 1.3 Annotate CSS variables and extract CSS docs

		Ensure, that all CSS variables of your component (starting with `--db-...` in the `[component].scss`) are annotated with [SassDoc](http://sassdoc.com/). Then run the script. It scans `packages/components/src/components` for subfolders (each component) and loads each component's SCSS file and transforms them into Markdown.


		### 1.2 Generate code examples via Mitosis

		Create a `.docs.lite.tsx` file in the docs directory of the component containing examples for your component. Then run the Mitosis build to extract code snippets (React, Angular, Vue) from your `.docs.lite.tsx` files:

Documentation for dev and copilot #4384

Are you sure you want to change the base?

Documentation for dev and copilot #4384

Conversation

michaelmkraus commented Jun 16, 2025 • edited by nmerget Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Types of changes

Further comments

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

michaelmkraus commented Jun 16, 2025 •

edited by nmerget

Loading