Add ability to include compiled code in markdowns

grigasp commented 1 month ago

Prerequisite for https://github.com/iTwin/presentation/issues/423.

The problem with including code into markdowns is that it can easily get obsolete. Even in case of the README.md we had an example that didn't really work... So it's much better if we extract the code from projects that compile and run. My approach adds some artifacts to markdown files, but they're not displayed in preview mode, so IMO that's okay.

The workflow would be like this:

You write a markdown and, instead of adding a piece of code, you add this:
```

```
Then, in some package that gets compiled - ideally our full stack tests or the test app - wrap the piece of code like this:
```
// __PUBLISH_EXTRACT_START__ Code.Piece.Identifier
// a piece of code to be extracted
// __PUBLISH_EXTRACT_END__
```
Note: __PUBLISH_EXTRACT_START__ and __PUBLISH_EXTRACT_END__ tags are already used in itwinjs-core.
Run pnpm lage docs to get code pieces extracted.
Run pnpm lage update-extractions to inject those pieces in appropriate places. This modifies the target markdown files - review the changes and commit them.
The pipeline is set up to run pnpm lage check-extractions, which does pretty much the same as update-extractions, but fails if any changes to target files are detected. So CI will fail if you forget steps 3-4.

I understand this is not ideal and involves quite a few steps, but we're not adding / editing those code pieces to markdowns that often, so IMO a little bit of inconvenience is justified by the fact that we'll not have out-of-date code examples.

@iTwin/itwinjs-core-presentation, waiting for opinions about this approach.

changeset-bot[bot] commented 1 month ago

⚠️ No Changeset found

Latest commit: 1226dd94458fb08be398a4211c48ca39f918f387

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions[bot] commented 1 month ago

Hierarchies benchmark

Benchmark suite	Current: 1226dd94458fb08be398a4211c48ca39f918f387	Previous: b9598f6702bea0f466abae02378a0c958f8e5fe9	Deviation	Status
`flat 50k elements list`	`4120.87` ms	`4090.82` ms	`0.7346%`	🚨
`flat 50k elements list (P95 of main thread blocks)`	`73` ms	`70` ms	`4.2857%`	🚨
`grouping by label`	`10073.95` ms	`9810.32` ms	`2.6873%`	🚨
`grouping by label (P95 of main thread blocks)`	`61` ms	`57` ms	`7.0175%`	🚨
`grouping by class`	`10263.34` ms	`9948.61` ms	`3.1636%`	🚨
`grouping by class (P95 of main thread blocks)`	`45` ms	`39` ms	`15.3846%`	🚨
`grouping by property`	`10696.21` ms	`10461.93` ms	`2.2394%`	🚨
`grouping by property (P95 of main thread blocks)`	`49` ms	`83` ms	`-40.9639%`	✅
`grouping by base class (10 classes)`	`7558.21` ms	`7184.68` ms	`5.1990%`	🚨
`grouping by base class (10 classes) (P95 of main thread blocks)`	`80` ms	`72` ms	`11.1111%`	🚨
`grouping by multiple attributes`	`27314.85` ms	`26658.02` ms	`2.4639%`	🚨
`grouping by multiple attributes (P95 of main thread blocks)`	`50` ms	`47` ms	`6.3830%`	🚨
`hide if no children required to finalize root, w/o children`	`46965.71` ms	`45797.8` ms	`2.5501%`	🚨
`hide if no children required to finalize root, w/o children (P95 of main thread blocks)`	`40` ms	`38` ms	`5.2632%`	🚨
`hide if no children required to finalize root, w/ children`	`164.28` ms	`152.33` ms	`7.8448%`	🚨
`hide if no children required to finalize root, w/ children (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`models tree initial (Baytown)`	`43.54` ms	`38.34` ms	`13.5629%`	🚨
`models tree initial (Baytown) (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`models tree full (Baytown)`	`7705.71` ms	`7571.11` ms	`1.7778%`	🚨
`models tree full (Baytown) (P95 of main thread blocks)`	`88` ms	`87` ms	`1.1494%`	🚨

This comment was automatically generated by workflow using github-action-benchmark.

github-actions[bot] commented 1 month ago

Unified selection benchmark

Benchmark suite	Current: 1226dd94458fb08be398a4211c48ca39f918f387	Previous: b9598f6702bea0f466abae02378a0c958f8e5fe9	Deviation	Status
`hilite 50k elements`	`1270.08` ms	`1197.81` ms	`6.0335%`	🚨
`hilite 50k elements (P95 of main thread blocks)`	`45` ms	`45` ms	`0%`	🟰
`hilite 50k group elements`	`232.91` ms	`241.39` ms	`-3.5130%`	✅
`hilite 50k group elements (P95 of main thread blocks)`	`31` ms	`31` ms	`0%`	🟰
`hilite 1k subjects`	`47509.86` ms	`47428.79` ms	`0.1709%`	🚨
`hilite 1k subjects (P95 of main thread blocks)`	`34` ms	`26` ms	`30.7692%`	🚨
`hilite 50k subcategories`	`277.44` ms	`280.51` ms	`-1.0944%`	✅
`hilite 50k subcategories (P95 of main thread blocks)`	`32` ms	`33` ms	`-3.0303%`	✅
`hilite 50k functional 3D elements`	`25767.37` ms	`26510.05` ms	`-2.8015%`	✅
`hilite 50k functional 3D elements (P95 of main thread blocks)`	`34` ms	`39` ms	`-12.8205%`	✅
`hilite 50k functional 2D elements`	`6202.1` ms	`6091.73` ms	`1.8118%`	🚨
`hilite 50k functional 2D elements (P95 of main thread blocks)`	`37` ms	`37` ms	`0%`	🟰
`compute selection for 50k elements`	`313.3` ms	`309.3` ms	`1.2932%`	🚨
`compute selection for 50k elements (P95 of main thread blocks)`	`31` ms	`31` ms	`0%`	🟰
`compute parent selection for 50k elements`	`346.78` ms	`348.94` ms	`-0.6190%`	✅
`compute parent selection for 50k elements (P95 of main thread blocks)`	`31` ms	`32` ms	`-3.1250%`	✅
`compute top ancestor selection for 50k elements`	`572.26` ms	`561.28` ms	`1.9562%`	🚨
`compute top ancestor selection for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute category selection for 50k elements`	`97.36` ms	`91.6` ms	`6.2882%`	🚨
`compute category selection for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute model selection for 50k elements`	`76.86` ms	`90.55` ms	`-15.1187%`	✅
`compute model selection for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute functional selection for 50k 3D elements`	`454.73` ms	`406.3` ms	`11.9198%`	🚨
`compute functional selection for 50k 3D elements (P95 of main thread blocks)`	`31` ms	`31` ms	`0%`	🟰
`compute parent functional selection for 50k 3D elements`	`492.64` ms	`449.19` ms	`9.6730%`	🚨
`compute parent functional selection for 50k 3D elements (P95 of main thread blocks)`	`35` ms	`31` ms	`12.9032%`	🚨
`compute top ancestor functional selection for 50k 3D elements`	`1206.5` ms	`1147.78` ms	`5.1160%`	🚨
`compute top ancestor functional selection for 50k 3D elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute functional selection for 50k 2D elements`	`3171.8` ms	`3034.42` ms	`4.5274%`	🚨
`compute functional selection for 50k 2D elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute parent functional selection for 50k 2D elements`	`3156.79` ms	`3011.11` ms	`4.8381%`	🚨
`compute parent functional selection for 50k 2D elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨
`compute top ancestor functional selection for 50k 2D elements`	`3223.33` ms	`2995.01` ms	`7.6233%`	🚨
`compute top ancestor functional selection for 50k 2D elements (P95 of main thread blocks)`	`0` ms	`0` ms	`NaN%`	🚨

This comment was automatically generated by workflow using github-action-benchmark.

iTwin / presentation