Move documentation of 'visibility' to a separate page
Visibility is a core concept (you have to know about when you create a 2nd package).
It shouldn't be hidden in a table, inside the list of common attributes.
I also plan to expand the documentation. Creating a proper section for visibility will leave more space for structuring the content.
This change doesn't modify the content itself (except for one introduction sentence).
https://github.com/bazelbuild/bazel/issues/8982
RELNOTES: None.
PiperOrigin-RevId: 311371192
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index c99bc94..dc93480 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -102,6 +102,7 @@
<li><a href="/versions/{{ current_version }}/external.html">External dependencies</a></li>
<li><a href="/versions/{{ current_version }}/configurable-attributes.html">Configurable attributes</a></li>
<li><a href="/versions/master/platforms-intro.html">Platforms and toolchains</a></li>
+ <li><a href="/versions/master/visibility.html">Visibility</a></li>
</ul>
</li>
diff --git a/site/docs/visibility.md b/site/docs/visibility.md
new file mode 100644
index 0000000..bcc5d2c
--- /dev/null
+++ b/site/docs/visibility.md
@@ -0,0 +1,99 @@
+# Visibility
+
+Visibility controls whether a target can be used by other packages. It is an
+important tool to structure the code when a codebase grows: it lets developers
+distinguish between implementation details and libraries other people can depend
+on.
+
+There are five forms (and one temporary form) a visibility label can take:
+
+* `["//visibility:public"]`: Anyone can use this rule.
+* `["//visibility:private"]`: Only rules in this package can use this rule.
+ Rules in `javatests/foo/bar` can always use rules in `java/foo/bar`.
+* `["//some/package:__pkg__", "//other/package:__pkg__"]`: Only rules in
+ `some/package` and `other/package` (defined in `some/package/BUILD` and
+ `other/package/BUILD`) have access to this rule. Note that sub-packages do
+ not have access to the rule; for example, `//some/package/foo:bar` or
+ `//other/package/testing:bla` wouldn't have access. `__pkg__` is a special
+ target and must be used verbatim. It represents all of the rules in the
+ package.
+* `["//project:__subpackages__", "//other:__subpackages__"]`: Only rules in
+ packages `project` or `other` or in one of their sub-packages have access to
+ this rule. For example, `//project:rule`, `//project/library:lib` or
+ `//other/testing/internal:munge` are allowed to depend on this rule (but not
+ `//independent:evil`)
+* `["//some/package:my_package_group"]`: A
+ [package group](be/functions.html#package_group) is a named set of package
+ names. Package groups can also grant access rights to entire subtrees,
+ e.g.`//myproj/...`.
+
+The visibility specifications of `//visibility:public` and
+`//visibility:private` can not be combined with any other visibility
+specifications.
+
+A visibility specification may contain a combination of package labels (i.e.
+`//foo:__pkg__`) and `package_group`s.
+
+If a rule does specify the visibility attribute, that specification overrides
+any [`default_visibility`](be/functions.html#package.default_visibility)
+attribute of the [`package`](functions.html#package) statement in the BUILD
+file containing the rule.
+
+Otherwise, if a rule does not specify the visibility attribute, the
+default_visibility of the package is used (except for
+[`exports_files`](be/functions.html#exports_files)).
+
+Otherwise, if the default_visibility for the package is not specified,
+`//visibility:private` is used.
+
+## Example
+
+File `//frobber/bin/BUILD`:
+
+```python
+# This rule is visible to everyone
+cc_binary(
+ name = "executable",
+ visibility = ["//visibility:public"],
+ deps = [":library"],
+)
+
+# This rule is visible only to rules declared in the same package
+cc_library(
+ name = "library",
+ visibility = ["//visibility:private"],
+)
+
+# This rule is visible to rules in package //object and //noun
+cc_library(
+ name = "subject",
+ visibility = [
+ "//noun:__pkg__",
+ "//object:__pkg__",
+ ],
+)
+
+# See package group "//frobber:friends" (below) for who can
+# access this rule.
+cc_library(
+ name = "thingy",
+ visibility = ["//frobber:friends"],
+)
+```
+
+File `//frobber/BUILD`:
+
+```python
+# This is the package group declaration to which rule
+# //frobber/bin:thingy refers.
+#
+# Our friends are packages //frobber, //fribber and any
+# subpackage of //fribber.
+package_group(
+ name = "friends",
+ packages = [
+ "//fribber/...",
+ "//frobber",
+ ],
+)
+```
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html
index 384c5cd..3c30891 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html
@@ -4,106 +4,6 @@
otherwise.</code></p>
<p>
-The <code>visibility</code> attribute on a rule controls whether
-the rule can be used by other packages. Rules are always visible to
-other rules declared in the same package.
+The <code>visibility</code> attribute on a rule controls whether the rule can
+be used by other packages. See the documentation for <a href="../visibility.md">visibility</a>.
</p>
-
-<p>There are five forms (and one temporary form) a visibility label can take:
-<ul>
-<li><code>["//visibility:public"]</code>: Anyone can use this rule.</li>
-<li><code>["//visibility:private"]</code>: Only rules in this package
-can use this rule. Rules in <code>javatests/foo/bar</code>
-can always use rules in <code>java/foo/bar</code>.
-</li>
-<li><code>["//some/package:__pkg__", "//other/package:__pkg__"]</code>:
-Only rules in <code>some/package</code> and <code>other/package</code>
-(defined in <code>some/package/BUILD</code> and
-<code>other/package/BUILD</code>) have access to this rule. Note that
-sub-packages do not have access to the rule; for example,
-<code>//some/package/foo:bar</code> or
-<code>//other/package/testing:bla</code> wouldn't have access.
-<code>__pkg__</code> is a special target and must be used verbatim.
-It represents all of the rules in the package.
-</li>
-<li><code>["//project:__subpackages__", "//other:__subpackages__"]</code>:
-Only rules in packages <code>project</code> or <code>other</code> or
-in one of their sub-packages have access to this rule. For example,
-<code>//project:rule</code>, <code>//project/library:lib</code> or
-<code>//other/testing/internal:munge</code> are allowed to depend on
-this rule (but not <code>//independent:evil</code>)
-</li>
-<li><code>["//some/package:my_package_group"]</code>:
-A <a href="${link package_group}">package group</a> is
-a named set of package names. Package groups can also grant access rights
-to entire subtrees, e.g.<code>//myproj/...</code>.
-</li>
-
-</ul>
-<p>The visibility specifications of
-
-<code>//visibility:public</code> and <code>//visibility:private</code>
-can not be combined with any other visibility specifications.
-A visibility specification may contain a combination of package labels
-(i.e. <code>//foo:__pkg__</code>) and <code>package_group</code>s.</p>
-<p>If a rule does specify the visibility attribute, that specification
-overrides any
-<code><a href="${link package.default_visibility}">default_visibility</a></code>
-attribute of the <code><a href="${link package}">package</a></code>
-statement in the BUILD file containing the rule.</p>
-<p>Otherwise, if a rule does not specify the visibility attribute, the default_visibility
-of the package is used (except for
-<a href="${link exports_files}">exports_files</a>).</p>
-<p>Otherwise, if the default_visibility for the package is not specified,
-<code>//visibility:private</code> is used.</p>
-<p><b>Example</b>:</p>
-<p>
-File <code>//frobber/bin/BUILD</code>:
-</p>
-<pre class="code">
-# This rule is visible to everyone
-cc_binary(
- name = "executable",
- visibility = ["//visibility:public"],
- deps = [":library"],
-)
-
-# This rule is visible only to rules declared in the same package
-cc_library(
- name = "library",
- visibility = ["//visibility:private"],
-)
-
-# This rule is visible to rules in package //object and //noun
-cc_library(
- name = "subject",
- visibility = [
- "//noun:__pkg__",
- "//object:__pkg__",
- ],
-)
-
-# See package group "//frobber:friends" (below) for who can
-# access this rule.
-cc_library(
- name = "thingy",
- visibility = ["//frobber:friends"],
-)
-</pre>
-<p>
-File <code>//frobber/BUILD</code>:
-</p>
-<pre class="code">
-# This is the package group declaration to which rule
-# //frobber/bin:thingy refers.
-#
-# Our friends are packages //frobber, //fribber and any
-# subpackage of //fribber.
-package_group(
- name = "friends",
- packages = [
- "//fribber/...",
- "//frobber",
- ],
-)
-</pre>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
index 4c51900..36891b2 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
@@ -60,9 +60,8 @@
<p>Every rule in this package has the visibility specified in this
attribute, unless otherwise specified in the <code>visibility</code>
attribute of the rule. For detailed information about the syntax of this
- attribute, see the documentation of the
- <a href="common-definitions.html#common.visibility">visibility</a>
- attribute. The package default visibility does not apply to
+ attribute, see the documentation of <a href="../visibility.md">visibility</a>.
+ The package default visibility does not apply to
<a href="#exports_files">exports_files</a>, which is
public by default.</p>
</td>
