docs: update docs for release

bazel-contrib · Jun 6, 2019 · 2834d9a · 2834d9a
1 parent 0976086
commit 2834d9a
Show file tree

Hide file tree

Showing 4 changed files with 167 additions and 17 deletions.
diff --git a/DEVELOPING.md b/DEVELOPING.md
@@ -42,9 +42,9 @@ Check if there are any breaking changes since the last tag - if so, this will be
 1. `yarn install`
 1. Re-generate the API docs: `yarn skydoc`
 1. `git add docs/` (in case new files were created)
-1. `git commit -a -m 'Update docs for release'`
+1. `git commit -a -m 'docs: update docs for release'`
 1. `npm config set tag-version-prefix ''` (we don't put a "v" prefix on our tags)
-1. `npm version minor -m 'rel: %s'` (replace `minor` with `patch` if no breaking changes)
+1. `npm version minor -m 'chore: release %s'` (replace `minor` with `patch` if no breaking changes)
 1. Build npm packages and publish them: `./scripts/publish_release.sh`
 1. `git push upstream && git push upstream --tags`
 1. (Manual for now): go to the [releases] page, edit the release with rough changelog (especially note any breaking changes!) and upload the release artifact from `rules_nodejs-[version].tar.gz` 

diff --git a/docs/node/node.html b/docs/node/node.html
@@ -318,10 +318,62 @@ <h3 id="nodejs_binary_args">Attributes</h3>
     <tr id="nodejs_binary.entry_point">
       <td><code>entry_point</code></td>
       <td>
-        <p><code>String; Required</code></p>
-        <p>The script which should be executed first, usually containing a main function.
-        This attribute expects a string starting with the workspace name, so that it's not ambiguous
-        in cases where a script with the same name appears in another directory or external workspace.</p>
+        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p>
+        <p>The script which should be executed first, usually containing a main function.</p>
+<pre><code>    If the entry JavaScript file belongs to the same package (as the BUILD file), 
+    you can simply reference it by its relative name to the package directory:
+
+    ```
+    nodejs_binary(
+        name = "my_binary",
+        ...
+        entry_point = ":file.js",
+    )
+    ```
+
+    You can specify the entry point as a typescript file so long as you also include
+    the ts_library target in data:
+
+    ```
+    ts_library(
+        name = "main",
+        srcs = ["main.ts"],
+    )
+
+    nodejs_binary(
+        name = "bin",
+        data = [":main"]
+        entry_point = ":main.ts",
+    )
+    ```
+
+    The rule will use the corresponding `.js` output of the ts_library rule as the entry point.
+
+    If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule. 
+    For example:
+
+    ```
+    filegroup(
+        name = "entry_file",
+        srcs = ["main.js"],
+    )
+
+    nodejs_binary(
+        name = "my_binary",
+        entry_point = ":entry_file",
+    )
+    ```
+
+    The entry_point can also be a label in another workspace:
+
+    ```
+    nodejs_binary(
+        name = "history-server",
+        entry_point = "@npm//node_modules/history-server:modules/cli.js",
+        data = ["@npm//history-server"],
+    )
+    ```
+</code></pre>
       </td>
     </tr>
     <tr id="nodejs_binary.install_source_map_support">
@@ -336,7 +388,7 @@ <h3 id="nodejs_binary_args">Attributes</h3>
     <tr id="nodejs_binary.node">
       <td><code>node</code></td>
       <td>
-        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node</code></p>
+        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node_bin</code></p>
         <p>The node entry point target.</p>
       </td>
     </tr>
@@ -488,10 +540,62 @@ <h3 id="nodejs_test_args">Attributes</h3>
     <tr id="nodejs_test.entry_point">
       <td><code>entry_point</code></td>
       <td>
-        <p><code>String; Required</code></p>
-        <p>The script which should be executed first, usually containing a main function.
-        This attribute expects a string starting with the workspace name, so that it's not ambiguous
-        in cases where a script with the same name appears in another directory or external workspace.</p>
+        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p>
+        <p>The script which should be executed first, usually containing a main function.</p>
+<pre><code>    If the entry JavaScript file belongs to the same package (as the BUILD file), 
+    you can simply reference it by its relative name to the package directory:
+
+    ```
+    nodejs_binary(
+        name = "my_binary",
+        ...
+        entry_point = ":file.js",
+    )
+    ```
+
+    You can specify the entry point as a typescript file so long as you also include
+    the ts_library target in data:
+
+    ```
+    ts_library(
+        name = "main",
+        srcs = ["main.ts"],
+    )
+
+    nodejs_binary(
+        name = "bin",
+        data = [":main"]
+        entry_point = ":main.ts",
+    )
+    ```
+
+    The rule will use the corresponding `.js` output of the ts_library rule as the entry point.
+
+    If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule. 
+    For example:
+
+    ```
+    filegroup(
+        name = "entry_file",
+        srcs = ["main.js"],
+    )
+
+    nodejs_binary(
+        name = "my_binary",
+        entry_point = ":entry_file",
+    )
+    ```
+
+    The entry_point can also be a label in another workspace:
+
+    ```
+    nodejs_binary(
+        name = "history-server",
+        entry_point = "@npm//node_modules/history-server:modules/cli.js",
+        data = ["@npm//history-server"],
+    )
+    ```
+</code></pre>
       </td>
     </tr>
     <tr id="nodejs_test.expected_exit_code">
@@ -513,7 +617,7 @@ <h3 id="nodejs_test_args">Attributes</h3>
     <tr id="nodejs_test.node">
       <td><code>node</code></td>
       <td>
-        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node</code></p>
+        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node_bin</code></p>
         <p>The node entry point target.</p>
       </td>
     </tr>

diff --git a/docs/node/node_repositories.html b/docs/node/node_repositories.html
@@ -188,7 +188,8 @@ <h3 id="node_repositories_args">Attributes</h3>
       <td><code>node_version</code></td>
       <td>
         <p><code>Unknown; Optional</code></p>
-        <p>optional; the specific version of NodeJS to install.</p>
+        <p>optional; the specific version of NodeJS to install or, if
+vendored_node is specified, the vendored version of node.</p>
       </td>
     </tr>
     <tr id="node_repositories.yarn_version">
@@ -202,7 +203,10 @@ <h3 id="node_repositories_args">Attributes</h3>
       <td><code>vendored_node</code></td>
       <td>
         <p><code>Unknown; Optional</code></p>
-        <p>optional; the local path to a pre-installed NodeJS runtime.</p>
+        <p>optional; the local path to a pre-installed NodeJS runtime.
+If set then also set node_version to the version that of node that is vendored.
+Bazel will automatically turn on features such as --preserve-symlinks-main if they
+are supported by the node version being used.</p>
       </td>
     </tr>
     <tr id="node_repositories.vendored_yarn">

diff --git a/docs/rollup/rollup_bundle.html b/docs/rollup/rollup_bundle.html
@@ -504,9 +504,51 @@ <h3 id="rollup_bundle_args">Attributes</h3>
     <tr id="rollup_bundle.entry_point">
       <td><code>entry_point</code></td>
       <td>
-        <p><code>String; Required</code></p>
-        <p>The starting point of the application, passed as the <code>--input</code> flag to rollup.
-        This should be a path relative to the workspace root.</p>
+        <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p>
+        <p>The starting point of the application, passed as the <code>--input</code> flag to rollup.</p>
+<pre><code>    If the entry JavaScript file belongs to the same package (as the BUILD file), 
+    you can simply reference it by its relative name to the package directory:
+
+    ```
+    rollup_bundle(
+        name = "bundle",
+        entry_point = ":main.js",
+    )
+    ```
+
+    You can specify the entry point as a typescript file so long as you also include
+    the ts_library target in deps:
+
+    ```
+    ts_library(
+        name = "main",
+        srcs = ["main.ts"],
+    )
+
+    rollup_bundle(
+        name = "bundle",
+        deps = [":main"]
+        entry_point = ":main.ts",
+    )
+    ```
+
+    The rule will use the corresponding `.js` output of the ts_library rule as the entry point.
+
+    If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule. 
+    For example:
+
+    ```
+    filegroup(
+        name = "entry_file",
+        srcs = ["main.js"],
+    )
+
+    rollup_bundle(
+        name = "bundle",
+        entry_point = ":entry_file",
+    )
+    ```
+</code></pre>
       </td>
     </tr>
     <tr id="rollup_bundle.global_name">