Docs: Adding pages for complexity and metrics plugins, fixing redirects, restoring getting-started content by kharrop · Pull Request #707 · player-ui/player

kharrop · 2025-08-20T19:30:29Z

Fixing redirects and adding docs around tooling, specifically complexity + metrics LSP plugins, restoring getting-started content.

Change Type (required)

Indicate the type of change your pull request is:

patch
minor
major
N/A

Does your PR have any documentation updates?

Updated docs
No Update needed
Unable to update docs

codecov · 2025-08-20T19:43:46Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.87%. Comparing base (cd3746f) to head (87571db).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #707   +/-   ##
=======================================
  Coverage   86.87%   86.87%           
=======================================
  Files         503      503           
  Lines       25660    25660           
  Branches     2630     2630           
=======================================
  Hits        22292    22292           
  Misses       3045     3045           
  Partials      323      323

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

KVSRoyal · 2025-08-27T02:51:14Z

+
+import { PackageManagers } from "starlight-package-managers";
+
+Generate diagnostics for content complexity using `@player-tools/complexity-check-plugin`. The plugin analyzes your content structure and calculates complexity based on asset types, nesting depth, and overall structure to provide a single complexity score per file.


Would it be clearer to say "DSL content" or "JSON content"? Or even just capitalize "Content"?

When I initially read this, I didn't understand what this plugin did at all. I think I read "content" as the general use of the word instead of Player Content. We use "content" a lot in the player space, despite it actually being a very ambiguous and common word. I think that can be confusing. But it's a pattern we have established so I leave whether to change it up to you.

For my own knowledge / not a review question: what is the purpose of the complexity check plugin? Are we trying to get consumers to limit complexity to less than a certain number?

FWIW I would go with Player Content. Its worth making a distinction when it comes to how its authored, but in general content (or player content) is generally what the input data for Player is referred to.

I'll update to Player Content 👍 .

@KVSRoyal there is a correlation between complexity score and time to render - so the higher the complexity, the worse it is because there's a lot to parse/run-time implications. So the warning/error numbers are to help identify which files could stand to be broken up into smaller parts. Because the plugin provides these complexity scores, we can use them in other utils like comparing PR changes to base branches, etc.

KVSRoyal · 2025-08-27T02:51:31Z

+
+Install the plugin:
+
+<PackageManagers pkg="@player-tools/complexity-check-plugin" />


This is cool. Didn't know we could use this.

KVSRoyal · 2025-08-27T02:59:03Z

+### Configuration Options
+
+- **`maxAcceptableComplexity`**: Maximum complexity before error (default: 10000)
+- **`maxWarningLevel`**: Complexity level that triggers warnings (default: 1000)
+- **`typeWeights`**: Custom complexity weights for different asset types
+- **`baseWeightOverrides`**: Override base complexity weights


Do you think we could leverage some docs auto-generator to transfer code docs into docs here? These types of things seem tedious to maintain and it's easier to put more detail if we only have to do it in one place.

Absolutely free to make this suggestion into a future ticket instead of doing it now. I don't expect you to redo a non-trivial part of how our docs work in this PR. 😅

100% yes. That's an issue I keep running into where the README of the source package has a lot of this and we're just repeating the same content. I'll make an issue to investigate streamlining this better.

KVSRoyal · 2025-08-27T03:00:41Z

+
+import { PackageManagers } from "starlight-package-managers";
+
+Generate a JSON file of metrics using `@player-tools/metrics-output-plugin`. The plugin consumes diagnostics from LSP plugins and produces a single JSON file with per-file metrics and optional project-level metadata.


What does "LSP" stand for here?

Language Service Protocol

Oh. Okay, can we link out to that? I don't think that's a common acronym 😅

Linking out seems excessive to me. If someone is reading about LSP/language plugins its not an unreasonable assumption that they are aware of what an LSP is. At the minimum though, I think it would be fine to our internal page on how our LSP is architected.

For now, I think since both of these plugins are under the language section, that it is a little self explanatory. That being said, I think having a more robust Plugin Overview page with glossary terms and additional context would be good.

KVSRoyal · 2025-08-27T03:01:40Z

@@ -21,153 +21,249 @@ You can do this by installing the React Player and Reference Assets Packages
  </Fragment>


Is this stuff and architecture.mdx just copied over from old docs?

Yep - definitely need some cleanup/updates here. Although, oops - didn't mean to include architecture; thanks for asking about it

…to metrics-docs

complexity and metrics docs added

d41c10a

kharrop added documentation Changes only affect the documentation skip-release Preserve the current version when merged labels Aug 20, 2025

kharrop marked this pull request as ready for review August 20, 2025 19:39

kharrop requested a review from a team as a code owner August 20, 2025 19:39

kharrop and others added 3 commits August 21, 2025 09:51

Merge branch 'main' into metrics-docs

4c2fe4c

moving to plugins section

059b80b

fixing redirects

10f39e3

kharrop changed the title ~~Docs: Adding pages for complexity and metrics plugins~~ Docs: Adding pages for complexity and metrics plugins, fixing redirects Aug 26, 2025

KetanReddy reviewed Aug 26, 2025

View reviewed changes

Comment thread docs/site/astro.config.mjs Outdated

converting path to a function

bc1ed2f

KVSRoyal reviewed Aug 26, 2025

View reviewed changes

Comment thread docs/site/src/content/docs/plugins/language/complexity-check.mdx

kharrop added 3 commits August 26, 2025 14:59

fixing sidebar and updating content to match other plugin pages

ca3f2c4

updating content

72d7785

updating example

fb11baa

KetanReddy previously approved these changes Aug 26, 2025

View reviewed changes

restoring getting-started

7d2c92d

kharrop dismissed KetanReddy’s stale review via 7d2c92d August 26, 2025 21:15

kharrop mentioned this pull request Aug 26, 2025

Docs: Updating Astro/Starlight, PageFind, Sidebar Enhancements #698

Merged

7 tasks

kharrop changed the title ~~Docs: Adding pages for complexity and metrics plugins, fixing redirects~~ Docs: Adding pages for complexity and metrics plugins, fixing redirects, restoring getting-started content Aug 26, 2025

KVSRoyal reviewed Aug 27, 2025

View reviewed changes

kharrop and others added 3 commits August 28, 2025 16:26

Merge branch 'main' into metrics-docs

1d20591

pr feedback

a87693c

Merge branch 'metrics-docs' of https://github.com/player-ui/player in…

87571db

…to metrics-docs

kharrop added patch Increment the patch version when merged and removed skip-release Preserve the current version when merged labels Aug 29, 2025

KVSRoyal approved these changes Aug 29, 2025

View reviewed changes

sugarmanz approved these changes Aug 29, 2025

View reviewed changes

kharrop merged commit 5d2f754 into main Aug 29, 2025
12 checks passed

kharrop deleted the metrics-docs branch August 29, 2025 15:36


		import { PackageManagers } from "starlight-package-managers";

		Generate diagnostics for content complexity using `@player-tools/complexity-check-plugin`. The plugin analyzes your content structure and calculates complexity based on asset types, nesting depth, and overall structure to provide a single complexity score per file.


		Install the plugin:

		<PackageManagers pkg="@player-tools/complexity-check-plugin" />


		import { PackageManagers } from "starlight-package-managers";

		Generate a JSON file of metrics using `@player-tools/metrics-output-plugin`. The plugin consumes diagnostics from LSP plugins and produces a single JSON file with per-file metrics and optional project-level metadata.

		@@ -21,153 +21,249 @@ You can do this by installing the React Player and Reference Assets Packages
		</Fragment>

Conversation

kharrop commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Type (required)

Does your PR have any documentation updates?

Uh oh!

codecov Bot commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

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!

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!

kharrop Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kharrop commented Aug 20, 2025 •

edited

Loading

codecov Bot commented Aug 20, 2025 •

edited

Loading

kharrop Aug 27, 2025 •

edited

Loading