Add reference docs for BUILD file symbols (#216)

This adds a new section to the reference docs:
`/2.x/reference/build-file-symbols/`. This renders all the known
non-target BUILD file symbols, as indicated by the
`name_to_build_file_info` key of the `help-all` output JSON.

This JSON looks like the following, and this generation basically just
mashes it up into documentation form:

```json
  "name_to_build_file_info": {
    "PANTS_VERSION": {
      "documentation": null,
      "is_target": false,
      "name": "PANTS_VERSION",
      "signature": null
    },
    "__defaults__": {
      "documentation": "Provide default field values.\n\nLearn more https://www.pantsbuild.org/2.22/docs/using-pants/key-concepts/targets-and-build-files#field-default-values",
      "is_target": false,
      "name": "__defaults__",
      "signature": "(*args: 'SetDefaultsT', ignore_unknown_fields: 'bool' = False, ignore_unknown_targets: 'bool' = False, **kwargs) -> 'None'"
    },
    "__dependencies_rules__": {
      "documentation": "Declare dependencies rules.",
      "is_target": false,
      "name": "__dependencies_rules__",
      "signature": "(*args, **kwargs) -> 'None'"
    },
    "__dependents_rules__": {
      "documentation": "Declare dependents rules.",
      "is_target": false,
      "name": "__dependents_rules__",
      "signature": "(*args, **kwargs) -> 'None'"
    },
    "_generator_sources_helper": {
      "documentation": null,
      "is_target": true,
      "name": "_generator_sources_helper",
      "signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
    },
    "_lockfile": {
      "documentation": null,
      "is_target": true,
      "name": "_lockfile",
      "signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
    },
...
```

This is a new sidebar option:


![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/e1e1a27c-9cc2-47e1-ac07-644a1c019ae8)


Some of these have reasonable docs:


![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/b453a0ad-055b-4ef9-b7b9-9528782f1d02)


![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/3f11ca66-85a2-49cc-87f4-fe36ed75a960)


Others do not have good docs:


![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/83df063c-2a59-434c-8d8e-878d6b57ac3e)


![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/121f3c2e-10a3-491c-b836-f9cad0256d31)



![image](https://github.com/pantsbuild/pantsbuild.org/assets/1203825/76a07178-de41-4022-b29c-56a6f04f191e)


I think we should land this and then separately work to improve the
documentation of each BUILD file symbol:

- pantsbuild/pants#20976
- pantsbuild/pants#20977
- pantsbuild/pants#20978
- pantsbuild/pants#20979
- pantsbuild/pants#20980


To make this work, there's two other changes required, which are done as
separate commits:

- support for back-tick code blocks, to avoid mangling them
- explicit sidebar positions, so that `BUILD file symbols` is placed
last, rather than before `Global options` (thus becoming the default)

This generates back to the first version that include that (2.16) and
involves some other changes to the code-genned docs, hence this is
targeted `automation:sync-docs`.

Fixes #212

docs/reference/build-file-symbols/PANTS_VERSION.mdx

@@ -0,0 +1,10 @@
+---
+title: PANTS_VERSION
+description: |
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`PANTS_VERSION`} signature={``}>
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/__defaults__.mdx

@@ -0,0 +1,15 @@
+---
+title: __defaults__
+description: |
+  Provide default field values.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`__defaults__`} signature={`(*args: 'SetDefaultsT', ignore_unknown_fields: 'bool' = False, ignore_unknown_targets: 'bool' = False, **kwargs) -> 'None'`}>
+
+Provide default field values.
+
+Learn more https://www.pantsbuild.org/2.22/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/__dependencies_rules__.mdx

@@ -0,0 +1,13 @@
+---
+title: __dependencies_rules__
+description: |
+  Declare dependencies rules.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`__dependencies_rules__`} signature={`(*args, **kwargs) -> 'None'`}>
+
+Declare dependencies rules.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/__dependents_rules__.mdx

@@ -0,0 +1,13 @@
+---
+title: __dependents_rules__
+description: |
+  Declare dependents rules.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`__dependents_rules__`} signature={`(*args, **kwargs) -> 'None'`}>
+
+Declare dependents rules.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "BUILD file symbols",
+  "link": {
+    "type": "generated-index",
+    "slug": "/reference/build-file-symbols",
+    "title": "BUILD file symbols"
+  },
+  "position": 5
+}

docs/reference/build-file-symbols/build_file_dir.mdx

@@ -0,0 +1,17 @@
+---
+title: build_file_dir
+description: |
+  Returns the path to the directory of the current BUILD file.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`build_file_dir`} signature={`() -> 'PurePath'`}>
+
+Returns the path to the directory of the current BUILD file.
+
+The returned value is an instance of `PurePath` to make path name manipulations easy.
+
+See: https://docs.python.org/3/library/pathlib.html#pathlib.PurePath
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/duplicate_rule.mdx

@@ -0,0 +1,13 @@
+---
+title: duplicate_rule
+description: |
+  DeployJarDuplicateRule(pattern: 'str', action: 'str')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`duplicate_rule`} signature={`(pattern: 'str', action: 'str') -> None`}>
+
+DeployJarDuplicateRule(pattern: &#x27;str&#x27;, action: &#x27;str&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/env.mdx

@@ -0,0 +1,13 @@
+---
+title: env
+description: |
+  Reference environment variable.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`env`} signature={`(name: 'str', *args, **kwargs) -> 'Any'`}>
+
+Reference environment variable.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/http_source.mdx

@@ -0,0 +1,13 @@
+---
+title: http_source
+description: |
+  http_source(url: 'str', *, len: 'int', sha256: 'str', filename: 'str' = '')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`http_source`} signature={`(url: 'str', *, len: 'int', sha256: 'str', filename: 'str' = '')`}>
+
+http_source(url: &#x27;str&#x27;, \*, len: &#x27;int&#x27;, sha256: &#x27;str&#x27;, filename: &#x27;str&#x27; = &#x27;&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/jvm_exclude.mdx

@@ -0,0 +1,13 @@
+---
+title: jvm_exclude
+description: |
+  JvmArtifactExclusion(group: 'str', artifact: 'str | None' = None)
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`jvm_exclude`} signature={`(group: 'str', artifact: 'str | None' = None) -> None`}>
+
+JvmArtifactExclusion(group: &#x27;str&#x27;, artifact: &#x27;str | None&#x27; = None)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/node_build_script.mdx

@@ -0,0 +1,16 @@
+---
+title: node_build_script
+description: |
+  A build script, mapped from the `scripts` section of a package.json file.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`node_build_script`} signature={`(entry_point: 'str', output_directories: 'Iterable[str]' = (), output_files: 'Iterable[str]' = (), extra_caches: 'Iterable[str]' = (), extra_env_vars: 'Iterable[str]' = ()) -> 'NodeBuildScript'`}>
+
+A build script, mapped from the `scripts` section of a package.json file.
+
+Either the `output_directories` or the `output_files` argument has to be set to capture the
+output artifacts of the build.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/node_test_script.mdx

@@ -0,0 +1,16 @@
+---
+title: node_test_script
+description: |
+  The test script for this package, mapped from the `scripts` section of a package.json
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`node_test_script`} signature={`(entry_point: 'str' = 'test', report_args: 'Iterable[str]' = (), report_output_files: 'Iterable[str]' = (), report_output_directories: 'Iterable[str]' = (), coverage_args: 'Iterable[str]' = (), coverage_output_files: 'Iterable[str]' = (), coverage_output_directories: 'Iterable[str]' = (), coverage_entry_point: 'str | None' = None) -> 'NodeTestScript'`}>
+
+The test script for this package, mapped from the `scripts` section of a package.json
+file. The pointed to script should accept a variadic number of ([ARG]...) path arguments.
+
+This entry point is the &#x22;test&#x22; script, by default.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/parametrize.mdx

@@ -0,0 +1,16 @@
+---
+title: parametrize
+description: |
+  A builtin function/dataclass that can be used to parametrize Targets.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`parametrize`} signature={`(*args: 'str', **kwargs: 'Any') -> 'None'`}>
+
+A builtin function/dataclass that can be used to parametrize Targets.
+
+Parametrization is applied between TargetAdaptor construction and Target instantiation, which
+means that individual Field instances need not be aware of it.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/per_platform.mdx

@@ -0,0 +1,52 @@
+---
+title: per_platform
+description: |
+  An object containing differing homogeneous platform-dependent values.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`per_platform`} signature={`(linux_arm64: '_T | None' = None, linux_x86_64: '_T | None' = None, macos_arm64: '_T | None' = None, macos_x86_64: '_T | None' = None) -> None`}>
+
+An object containing differing homogeneous platform-dependent values.
+
+The values should be evaluated for the execution environment, and not the host environment
+(I.e. it should be evaluated in a `rule` which requests `Platform`).
+
+Expected usage is roughly:
+
+```python
+class MyFieldType(...):
+    value = str | per_platform[str]
+
+    @classmethod
+    def compute_value(  # type: ignore[override]
+        cls,
+        raw_value: Optional[Union[str, per_platform[str]]],
+        address: Address,
+    ) -> Optional[Union[str, per_platform[str]]]:
+        if isinstance(raw_value, per_platform):
+            # NOTE: Ensure the values are homogeneous
+            raw_value.check_types(str)
+
+        return raw_value
+
+...
+
+@rule
+async def my_rule(..., platform: Platform) -> ...:
+    field_value = target[MyFieldType].value
+
+    if isinstance(field_value, per_platform):
+        field_value = field_value.get_value_for_platform(platform)
+
+    ...
+```
+
+NOTE: Support for this object should be heavily weighed, as it would be inappropriate to use in
+certain contexts (such as the `source` field in a `foo_source` target, where the intent is to
+support differing source files based on platform. The result would be that dependency inference
+(and therefore the dependencies field) wouldn&#x27;t be knowable on the host, which is not something
+the engine can support yet).
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/python_artifact.mdx

@@ -0,0 +1,13 @@
+---
+title: python_artifact
+description: |
+  Represents a Python setup.py-based project.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`python_artifact`} signature={`(**kwargs) -> None`}>
+
+Represents a Python setup.py-based project.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/scala_exclude.mdx

@@ -0,0 +1,13 @@
+---
+title: scala_exclude
+description: |
+  ScalaArtifactExclusion(group: 'str', artifact: 'str | None' = None, crossversion: 'str' = 'binary')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`scala_exclude`} signature={`(group: 'str', artifact: 'str | None' = None, crossversion: 'str' = 'binary') -> None`}>
+
+ScalaArtifactExclusion(group: &#x27;str&#x27;, artifact: &#x27;str | None&#x27; = None, crossversion: &#x27;str&#x27; = &#x27;binary&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/setup_py.mdx

@@ -0,0 +1,13 @@
+---
+title: setup_py
+description: |
+  Represents a Python setup.py-based project.
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`setup_py`} signature={`(**kwargs) -> None`}>
+
+Represents a Python setup.py-based project.
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/shading_keep.mdx

@@ -0,0 +1,13 @@
+---
+title: shading_keep
+description: |
+  JvmShadingKeepRule(pattern: 'str')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`shading_keep`} signature={`(pattern: 'str') -> None`}>
+
+JvmShadingKeepRule(pattern: &#x27;str&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/shading_relocate.mdx

@@ -0,0 +1,13 @@
+---
+title: shading_relocate
+description: |
+  JvmShadingRelocateRule(package: 'str', into: 'str | None' = None)
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`shading_relocate`} signature={`(package: 'str', into: 'str | None' = None) -> None`}>
+
+JvmShadingRelocateRule(package: &#x27;str&#x27;, into: &#x27;str | None&#x27; = None)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/shading_rename.mdx

@@ -0,0 +1,13 @@
+---
+title: shading_rename
+description: |
+  JvmShadingRenameRule(pattern: 'str', replacement: 'str')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`shading_rename`} signature={`(pattern: 'str', replacement: 'str') -> None`}>
+
+JvmShadingRenameRule(pattern: &#x27;str&#x27;, replacement: &#x27;str&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/shading_zap.mdx

@@ -0,0 +1,13 @@
+---
+title: shading_zap
+description: |
+  JvmShadingZapRule(pattern: 'str')
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`shading_zap`} signature={`(pattern: 'str') -> None`}>
+
+JvmShadingZapRule(pattern: &#x27;str&#x27;)
+
+</BuildFileSymbol>

docs/reference/build-file-symbols/stevedore_namespace.mdx

@@ -0,0 +1,22 @@
+---
+title: stevedore_namespace
+description: |
+  str(object='') -> str
+---
+
+import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
+
+<BuildFileSymbol name={`stevedore_namespace`} signature={``}>
+
+str(object=&#x27;&#x27;) -&#x3E; str
+str(bytes_or_buffer[, encoding[, errors]]) -&#x3E; str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.**str**() (if defined)
+or repr(object).
+encoding defaults to sys.getdefaultencoding().
+errors defaults to &#x27;strict&#x27;.
+
+</BuildFileSymbol>

docs/reference/global-options.mdx

@@ -2,6 +2,7 @@
 title: Global options
 description: |
   Options to control the overall behavior of Pants.
+sidebar_position: 1
 ---
 
 import Option from "@site/src/components/reference/Option";

docs/reference/goals/_category_.json

@@ -4,5 +4,6 @@
     "type": "generated-index",
     "slug": "/reference/goals",
     "title": "Goals"
-  }
+  },
+  "position": 2
 }

docs/reference/subsystems/_category_.json

@@ -4,5 +4,6 @@
     "type": "generated-index",
     "slug": "/reference/subsystems",
     "title": "Subsystems"
-  }
+  },
+  "position": 3
 }

docs/reference/targets/_category_.json

@@ -4,5 +4,6 @@
     "type": "generated-index",
     "slug": "/reference/targets",
     "title": "Targets"
-  }
+  },
+  "position": 4
 }