docs: start of docs for configure (#1094)

Co-authored-by: Jason Bedard <jason@aspect.dev>
GitOrigin-RevId: 46a28e0d5d104e5638c70c209ebc60e890c05dbb

Author: 2 people

cmd/aspect/configure/configure.go

@@ -34,9 +34,26 @@ func NewCmd(streams ioutils.Streams, languages map[string]language.Language) *co
 	v := configure.New(streams, languages)
 
 	cmd := &cobra.Command{
-		Use:     "configure",
-		Short:   "Update BUILD files for JavaScript, TypeScript, Go and Protobuf",
-		Long:    "Generates and updates BUILD files from sources for JavaScript, TypeScript, Go and Protobuf.",
+		Use:   "configure",
+		Short: "Auto-configure Bazel by updating BUILD files",
+		Long: `configure generates and updates BUILD files from source code.
+
+It is named after the "make configure" workflow which is typical in C++ projects, using
+[autoconf](https://www.gnu.org/software/autoconf/).
+
+configure is non-destructive: hand-edits to BUILD files are generally preserved.
+You can use a ` + "`#keep`" + ` directive to force the tool to leave existing BUILD contents alone.
+Run 'aspect help directives' for more documentation on directives.
+
+So far these languages are supported:
+- Go and Protocol Buffers, thanks to code from [gazelle]
+- JavaScript (including TypeScript)
+
+configure is based on [gazelle]. We are very grateful to the authors of that software.
+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
+`,
 		GroupID: "aspect",
 		RunE: interceptors.Run(
 			[]interceptors.Interceptor{

cmd/aspect/root/root.go

@@ -154,6 +154,11 @@ func NewCmd(
 		Short: "Conventions for tags which are special.",
 		Long:  mustReadFile("tags.md"),
 	})
+	cmd.AddCommand(&cobra.Command{
+		Use:   "directives",
+		Short: "Special comments in BUILD files which instruct Aspect CLI behaviors",
+		Long:  mustReadFile("directives.md"),
+	})
 
 	return cmd
 }

docs/help/topics/BUILD.bazel

@@ -4,6 +4,7 @@ go_library(
     name = "topics",
     srcs = ["doc.go"],
     embedsrcs = [
+        "directives.md",
         "info-keys.md",
         "tags.md",
         "target-syntax.md",

docs/help/topics/directives.md

@@ -0,0 +1,30 @@
+# Directives
+
+You can configure Aspect CLI using directives, which are just specially-formatted
+comments in `BUILD` files that govern behavior of the tool when visiting files
+within the Bazel package rooted at that file.
+
+## JavaScript
+
+JavaScript directives follow the same format as [gazelle](https://github.com/bazelbuild/bazel-gazelle#directives).
+
+Directives specific to JavaScript (and TypeScript) are as follows:
+
+| **Directive**                   | **Default value**           | **Param(s)**        |
+| ------------------------------- | --------------------------- | ------------------- |
+| `js`                            | `enabled`                   | `enabled\|disabled` |
+| `js_generation_mode`            | `directory`                 | `none\|directory`   |
+| `js_pnpm_lockfile`              | `pnpm-lock.yaml`            | _lockfile_          |
+| `js_ignore_imports`             |                             | _glob_              |
+| `js_resolve`                    |                             | _glob_ _target_     |
+| `js_validate_import_statements` | `true`                      | `true\|false`       |
+| `js_project_naming_convention`  | `$package_name$`            | _name_              |
+| `js_tests_naming_convention`    | `$package_name$_tests`      | _name_              |
+| `js_files`                      | `**/*.{ts,tsx}`             | _glob_              |
+| `js_test_files`                 | `**/*.{spec,test}.{ts,tsx}` | _glob_              |
+
+All JavaScript directives are specified via `gazelle` such as:
+
+```
+# gazelle:js enabled
+```