docs: add directives help topic as docs guide (#3044)

I'm not sure if we have to reference this somewhere to get it onto the
site? Where are the .md files converted to HTML?

Just copying the directives.md might be fine for now, but I think this
could also use some re-arranging and organizing. It's quite confusing
what should go into:
*
[guides/configure.md](https://github.com/aspect-build/silo/blob/main/docs/versioned/cli/commands/aspect_configure.md)
*
[commands/configure.md](https://github.com/aspect-build/silo/blob/main/docs/versioned/cli/commands/aspect_configure.md)
* [help/topics/directives.md](cli/core/docs/help/topics/directives.md)

Currently information is spread and a bit duplicated across all of
those, and it's unclear which direction thing should be linking etc.

---------

Co-authored-by: Jason Bedard <[email protected]>
Co-authored-by: Alex Eagle <[email protected]>
GitOrigin-RevId: a6f3b2503be36b1d512495ea1564153b416c17d9

cmd/aspect/configure/configure.go

@@ -53,6 +53,10 @@ configure is based on [gazelle]. We are very grateful to the authors of that sof
 The advantage of configure in Aspect CLI is that you don't need to compile the tooling before running it.
 
 [gazelle]: https://github.com/bazelbuild/bazel-gazelle
+
+To change the behavior of configure, you add "directives" to your BUILD files, which are comments
+in a special syntax.
+Run 'aspect help directives' or see https://docs.aspect.build/v/cli/help/directives for more info.
 `,
 		GroupID: "aspect",
 		RunE: interceptors.Run(

cmd/aspect/root/BUILD.bazel

@@ -33,10 +33,10 @@ go_library(
         "//cmd/aspect/sync",
         "//cmd/aspect/test",
         "//cmd/aspect/version",
-        "//docs/help/topics",
         "//pkg/aspect/root/flags",
         "//pkg/ioutils",
         "//pkg/plugin/system",
+        "//docs/help/topics",
         "@com_github_fatih_color//:color",
         "@com_github_mattn_go_isatty//:go-isatty",
         "@com_github_spf13_cobra//:cobra",

cmd/aspect/root/root.go

@@ -51,10 +51,10 @@ import (
 	"aspect.build/cli/cmd/aspect/sync"
 	"aspect.build/cli/cmd/aspect/test"
 	"aspect.build/cli/cmd/aspect/version"
-	"aspect.build/cli/docs/help/topics"
 	"aspect.build/cli/pkg/aspect/root/flags"
 	"aspect.build/cli/pkg/ioutils"
 	"aspect.build/cli/pkg/plugin/system"
+	help_docs "github.com/aspect-build/silo/docs/help/topics"
 )
 
 var (
@@ -168,7 +168,7 @@ func NewCmd(
 }
 
 func mustReadFile(f string) string {
-	result, err := topics.Content.ReadFile(f)
+	result, err := help_docs.Content.ReadFile(f)
 	if err != nil {
 		panic(fmt.Errorf("Internal error: embed data was not readable: %w", err))
 	}

docs/help/topics/directives.md

@@ -6,11 +6,39 @@ within the Bazel package rooted at that file.
 
 ## Go
 
-Go directives for generating BUILD files are from the standard [gazelle go plugin](https://github.com/bazelbuild/bazel-gazelle#directives).
+Go directives for generating BUILD files are from the standard [gazelle directives].
 
 ## JavaScript
 
-JavaScript directives for generating BUILD files follow the same format as [gazelle](https://github.com/bazelbuild/bazel-gazelle). In addition to the generic directives from the [standard gazelle directives](https://github.com/bazelbuild/bazel-gazelle#directives) JavaScript (and TypeScript) specific directives are as follows:
+JavaScript directives for generating BUILD files follow the same format as gazelle.
+You can use generic directives from the [gazelle directives], as well as the following JS/TS
+specific directives.
+
+TypeScript source files are those ending in `.ts`, `.tsx` as well as `.js`, `.mjs`.
+Test source files are source files ending with `.spec.ts` (and other ts extensions).
+The test file pattern can be configured with the 'js*test*\*' directives.
+
+By default `aspect configure` creates new BUILD files for each directory containing source files.
+This can be configured to only edit existing BUILD files using the `js_generation_mode` directive.
+
+Each BUILD file may have a `ts_project` rule for sources, another for tests,
+a `npm_package` rule for pnpm workspace projects, and `npm_link_all_packages` for linking node_modules.
+Which rules are configured depends on the source files and directives that apply.
+
+Next, all source files are collected into the `srcs` of the `ts_project`,
+either the primary rule or tests rule.
+
+Finally, the `import` statements in the source files are parsed, and
+dependencies are added to the `deps` attribute of the appropriate
+`ts_project` rule which the source file belongs to.
+
+Dependencies may also be found other ways such as from the CommonJS `require` function.
+
+If a `package.json` file exists declaring npm dependencies, a `npm_link_all_packages` rule
+is generated for declaring depending on individual NPM packages.
+
+If the `package.json` is a pnpm workspace project a `npm_package` rule may be generated to
+enable other projects to declare dependencies on the package.
 
 <!-- prettier-ignore-start -->
 | **Directive**                                           | **Default value**           |
@@ -40,3 +68,5 @@ JavaScript directives for generating BUILD files follow the same format as [gaze
 | `# gazelle:js_tsconfig _filename_`                      | `tsconfig.json`             |
 | Path to a `tsconfig.json` file used to help generate TypeScript rules.<br />This value is inherited by sub-directories and applied relative to each BUILD.<br />The `ts_project(tsconfig)` attribute is *NOT* set and must be done manually if necessary |
 <!-- prettier-ignore-end -->
+
+[gazelle directives]: https://github.com/bazelbuild/bazel-gazelle#directives

gazelle/js/config.go

@@ -13,7 +13,7 @@ import (
 	"github.com/emirpasic/gods/sets/treeset"
 )
 
-// Directives. Keep in sync with documentation in cli/core/docs/help/topics/directives.md
+// Directives. Keep in sync with documentation in /docs/help/topics/directives.md
 const (
 	// Directive_TypeScriptExtension represents the directive that controls whether
 	// this TypeScript generation is enabled or not. Sub-packages inherit this value.

pkg/plugin/sdk/v1alpha3/README.md

@@ -2,4 +2,4 @@
 
 This is the SDK for creating plugins for the Aspect CLI using the Go language.
 
-See https://aspect-build.github.io/aspect-cli/help/topics/plugins
+See https://docs.aspect.build/v/cli/plugins

pkg/plugin/sdk/v1alpha4/README.md

@@ -2,4 +2,4 @@
 
 This is the SDK for creating plugins for the Aspect CLI using the Go language.
 
-See https://aspect-build.github.io/aspect-cli/help/topics/plugins
+See https://docs.aspect.build/v/cli/plugins