fix(core): link to sync generators page during sync prompt, and provide more info on docs page for disabling and applyChanges (#28001)

This PR expands the concept page for sync generators to show config
examples for `applyChanges` and `disableTaskSyncGenerators`. It also
adds a link when during the sync prompt for users to read more about it.

<img width="1392" alt="Screenshot 2024-09-19 at 12 00 14 PM"
src="https://github.com/user-attachments/assets/a13f50b7-557a-4c76-8903-49486ebf4ff2">

Preview:
https://nx-dev-git-feat-sync-docs-and-links-nrwl.vercel.app/concepts/sync-generators

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #

docs/shared/concepts/sync-generators.md

@@ -15,7 +15,77 @@ Nx does this in different ways, depending on whether the task is being run on a
 
 On a developer machine, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the user is prompted to run the generator or skip it. This prompt can be disabled by setting the `sync.applyChanges` property to `true` or `false` in the `nx.json` file.
 
-In CI, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the `--skip-sync` flag when executing the task or you can skip an individual sync generator by adding that generator to the `sync.disabledTaskSyncGenerators` in `nx.json`.
+```json {% fileName="nx.json" highlightLines=["4-6"] %}
+{
+  "$schema": "packages/nx/schemas/nx-schema.json",
+  ...
+  "sync": {
+    "applyChanges": true
+  }
+}
+```
+
+{% callout type="warning" title="Opting out of automatic sync" %}
+If you set `sync.applyChanges` to `false`, then developers must run `nx sync` manually before pushing changes. Otherwise, CI may fail due to the workspace being out of sync.
+{% /callout %}
+
+In CI, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the `--skip-sync` flag when executing the task, or you can skip an individual sync generator by adding that generator to the `sync.disabledTaskSyncGenerators` in `nx.json`.
+
+```json {% fileName="nx.json" highlightLines=["4-6"] %}
+{
+  "$schema": "packages/nx/schemas/nx-schema.json",
+  ...
+  "sync": {
+    "disabledTaskSyncGenerators": ["@nx/js:typescript-sync"]
+  }
+}
+
+```
+
+Use the project details view to **find registered sync generators** for a given task.
+
+```shell
+nx show project <name>
+```
+
+The above command opens up the project details view, and the registered sync generators are under the **Sync Generators** for each target. Most sync generators are inferred when using an [inference plugin](/concepts/inferred-tasks). For example, the `@nx/js/typescript` plugin registers the `@nx/js:typescript-sync` generator on `build` and `typecheck` targets.
+
+{% project-details title="Project Details View" expandedTargets="build" %}
+
+```json
+{
+  "project": {
+    "name": "foo",
+    "data": {
+      "root": " packages/foo",
+      "projectType": "library",
+      "targets": {
+        "build": {
+          "dependsOn": ["^build"],
+          "cache": true,
+          "inputs": [
+            "{workspaceRoot}/tsconfig.base.json",
+            "{projectRoot}/tsconfig.lib.json",
+            "{projectRoot}/src/**/*.ts"
+          ],
+          "outputs": ["{workspaceRoot}/packages/foo/dist"],
+          "syncGenerators": ["@nx/js:typescript-sync"],
+          "executor": "nx:run-commands",
+          "options": {
+            "command": "tsc --build tsconfig.lib.json --pretty --verbose"
+          }
+        }
+      }
+    }
+  },
+  "sourceMap": {
+    "targets": ["packages/foo/tsconfig.ts", "@nx/js/typescript"],
+    "targets.build": ["packages/foo/tsconfig.ts", "@nx/js/typescript"]
+  }
+}
+```
+
+{% /project-details %}
 
 Task sync generators can be thought of like the `dependsOn` property, but for generators instead of task dependencies.
 

nx-dev/ui-markdoc/src/lib/tags/project-details.component.tsx

@@ -9,6 +9,7 @@ import {
 } from 'react';
 import { ProjectDetails as ProjectDetailsUi } from '@nx/graph-internal/ui-project-details';
 import { ExpandedTargetsProvider } from '@nx/graph/shared';
+import { twMerge } from 'tailwind-merge';
 
 export function Loading() {
   return (
@@ -110,7 +111,7 @@ export function ProjectDetails({
       )}
       <div
         id="project-details-container"
-        className="not-prose overflow-y-auto"
+        className={twMerge('not-prose', height && 'overflow-y-auto')}
         style={{ height }}
         ref={elementRef}
       >

packages/nx/src/tasks-runner/run-command.ts

@@ -491,7 +491,7 @@ async function promptForApplyingSyncGeneratorChanges(): Promise<boolean> {
       name: 'applyChanges',
       type: 'select',
       message:
-        'Would you like to sync the identified changes to get your worskpace up to date?',
+        'Would you like to sync the identified changes to get your workspace up to date?',
       choices: [
         {
           name: 'yes',
@@ -504,7 +504,7 @@ async function promptForApplyingSyncGeneratorChanges(): Promise<boolean> {
       ],
       footer: () =>
         chalk.dim(
-          '\nYou can skip this prompt by setting the `sync.applyChanges` option in your `nx.json`.'
+          '\nYou can skip this prompt by setting the `sync.applyChanges` option to `true` in your `nx.json`.\nFor more information, refer to the docs: https://nx.dev/concepts/sync-generators.'
         ),
     };