Skip to content

Commit

Permalink
fix nest getting-started
Browse files Browse the repository at this point in the history
  • Loading branch information
thejcannon committed Jan 2, 2024
1 parent 0954701 commit 494a90c
Show file tree
Hide file tree
Showing 331 changed files with 383 additions and 435 deletions.
2 changes: 1 addition & 1 deletion docs/docs/docker/docker-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ A Docker image is built from a recipe specified by a [Dockerfile](https://docs.d

Pants uses [`docker_image`](../../reference/targets/docker_image.mdx) [targets](../using-pants/key-concepts/targets-and-build-files.mdx) to indicate which Dockerfiles you want Pants to know about, and to add any necessary metadata.

You can generate initial BUILD files for your Docker images, using [tailor](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files):
You can generate initial BUILD files for your Docker images, using [tailor](../getting-started/initial-configuration.mdx#5-generate-build-files):

```
❯ pants tailor ::
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/getting-started/_category_.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"label": "Getting Started",
"position": 2
"label": "Getting started",
"position": 1
}
4 changes: 0 additions & 4 deletions docs/docs/getting-started/getting-started/_category_.json

This file was deleted.

File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion docs/docs/go/go-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ You may want to set the option `[golang].minimum_expected_version` to a value li

You can also set `[golang].go_search_paths` to influence where Pants looks for Go, e.g. `["/usr/bin"]`. It defaults to your `PATH`.

Then run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will add a `go_mod` target where you have your `go.mod` file, a `go_package` target for every directory with a `.go` file, and a `go_binary` target in every directory where you have `package main`.
Then run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will add a `go_mod` target where you have your `go.mod` file, a `go_package` target for every directory with a `.go` file, and a `go_binary` target in every directory where you have `package main`.

```
❯ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/go/integrations/protobuf.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Multiple Protobuf files can set the same `go_package` if their code should show

## Step 4: Generate `protobuf_sources` targets

Run [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `protobuf_sources` target wherever you have `.proto` files:
Run [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `protobuf_sources` target wherever you have `.proto` files:

```
❯ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/helm/helm-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ version: 0.1.0
You can use the `helm create` command to create an initial skeleton for your chart but be sure you have properly configured your source root patterns (as shown in the previous section) since the `helm create` command will create a folder name with the name of your chart and place the sources inside.
:::

Then run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate `BUILD` files. This will scan your source repository in search of `Chart.yaml` or `Chart.yml` files and create a `helm_chart` target for each of them.
Then run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files) to generate `BUILD` files. This will scan your source repository in search of `Chart.yaml` or `Chart.yml` files and create a `helm_chart` target for each of them.

```
❯ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/java-and-scala/java-and-scala-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ backend_packages = [
]
```

Then run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will create `java_sources` and `scala_sources` targets in every directory containing library code, as well as test targets like `scalatest_tests` and `junit_tests` for filenames that look like tests.
Then run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will create `java_sources` and `scala_sources` targets in every directory containing library code, as well as test targets like `scalatest_tests` and `junit_tests` for filenames that look like tests.

```
❯ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/java-and-scala/kotlin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ backend_packages = [

### Setting up targets

Run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will create `kotlin_sources` targets in every directory containing library code, as well as `kotlin_junit_tests` targets for filenames that look like tests.
Run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files. This will create `kotlin_sources` targets in every directory containing library code, as well as `kotlin_junit_tests` targets for filenames that look like tests.

```
❯ pants tailor ::
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/python/goals/test.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Pants will automatically include any relevant config files in the process's sand

Pytest uses [`conftest.py` files](https://docs.pytest.org/en/stable/fixture.html#conftest-py-sharing-fixture-functions) to share fixtures and config across multiple distinct test files.

The default `sources` value for the `python_test_utils` target includes `conftest.py`. You can run [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to automatically add this target:
The default `sources` value for the `python_test_utils` target includes `conftest.py`. You can run [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to automatically add this target:

```
pants tailor ::
Expand Down Expand Up @@ -406,7 +406,7 @@ $ pants test project/app_test.py --no-test-timeouts

Use the target type `python_source` for test utilities, rather than `python_test`.

To reduce boilerplate, you can use either the [`python_sources`](../../../reference/targets/python_sources.mdx) or [`python_test_utils`](../../../reference/targets/python_test_utils.mdx) targets to generate `python_source` targets. These behave the same, except that `python_test_utils` has a different default `sources` to include `conftest.py` and type stubs for tests (like `test_foo.pyi`). Use [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate both these targets automatically.
To reduce boilerplate, you can use either the [`python_sources`](../../../reference/targets/python_sources.mdx) or [`python_test_utils`](../../../reference/targets/python_test_utils.mdx) targets to generate `python_source` targets. These behave the same, except that `python_test_utils` has a different default `sources` to include `conftest.py` and type stubs for tests (like `test_foo.pyi`). Use [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to generate both these targets automatically.

For example:

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/python/integrations/aws-lambda.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ This adds the new `python_aws_lambda_function` target, which you can confirm by

First, add your lambda function in a Python file like you would [normally do with AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/python-handler.html). Specifically, create a function `def my_handler_name(event, context)` with the name you want.

Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to automate this.
Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to automate this.

Add a `python_aws_lambda_function` target and define the `runtime` and `handler` fields. The `runtime` should be one of the values from [https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html). The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/python/integrations/google-cloud-functions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ This adds the new `python_google_cloud_function` target, which you can confirm b

First, add your Cloud function in a Python file like you would [normally do with Google Cloud Functions](https://cloud.google.com/functions/docs/first-python), such as creating a function `def my_handler_name(event, context)` for event-based functions.

Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to automate this.
Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to automate this.

Add a `python_google_cloud_function` target and define the `runtime`, `handler`, and `type` fields. The `type` should be either `"event"` or `"http"`. The `runtime` should be one of the values from [https://cloud.google.com/functions/docs/concepts/python-runtime](https://cloud.google.com/functions/docs/concepts/python-runtime). The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/python/integrations/protobuf-and-grpc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Pants will then automatically add these dependencies to your `protobuf_source` t

## Step 3: Generate `protobuf_sources` target

Run [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `protobuf_sources` target wherever you have `.proto` files:
Run [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `protobuf_sources` target wherever you have `.proto` files:

```
$ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/python/integrations/thrift.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Pants will then automatically add these dependencies to your `thrift_sources` ta

## Step 3: Generate `thrift_sources` target

Run [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `thrift_sources` target wherever you have `.thrift` files:
Run [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) for Pants to create a `thrift_sources` target wherever you have `.thrift` files:

```
$ pants tailor ::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ python_sources(name="lib")
python_tests(name="tests")
```

You can generate these targets by running [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files).
You can generate these targets by running [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files).

```
❯ pants tailor ::
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/releases/upgrade-tips.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ ignore_warnings = [
Run `curl -L -o pants https://pantsbuild.github.io/setup/pants` to check if there have been any changes, e.g. adding support for running Pants with new Python interpreters.

:::caution Consider migrating to the new `pants` binary
The `pants` script is deprecated. The new `pants` binary has many improvements over the script, including an embedded Python runtime. The [installation page](../getting-started/getting-started/installing-pants.mdx) has more details on how to migrate.
The `pants` script is deprecated. The new `pants` binary has many improvements over the script, including an embedded Python runtime. The [installation page](../getting-started/installing-pants.mdx) has more details on how to migrate.
:::

## Find any bugs or issues?
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/shell/shell-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ backend_packages = [
]
```

Then, run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files:
Then, run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files) to generate BUILD files:

```
$ pants tailor ::
Expand Down Expand Up @@ -205,7 +205,7 @@ To use shunit2 with Pants:
1. Create a test file like `tests.sh`, `test_foo.sh`, or `foo_test.sh`.
- Refer to [https://github.com/kward/shunit2/](https://github.com/kward/shunit2/) for how to write shUnit2 tests.
2. Create a `shunit2_test` or `shunit2_tests` target in the directory's BUILD file.
- You can run [`pants tailor`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) to automate this step.
- You can run [`pants tailor`](../getting-started/initial-configuration.mdx#5-generate-build-files) to automate this step.
3. Specify which shell to run your tests with, either by setting a shebang directly in the test file or by setting the field `shell` on the `shunit2_test` / `shunit2_tests` target.
- See [here](../../reference/targets/shunit2_tests.mdx#codeshellcode) for all supported shells.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/terraform/terraform-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The Terraform backend has 2 target types:

### Modules

The `tailor` goal will automatically generate `terraform_module` targets. Run [`pants tailor ::`](../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files). For example:
The `tailor` goal will automatically generate `terraform_module` targets. Run [`pants tailor ::`](../getting-started/initial-configuration.mdx#5-generate-build-files). For example:

```
❯ pants tailor ::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,7 @@ To reduce boilerplate, Pants provides target types that generate other targets.
- `python_tests` -> `python_test`
- `go_mod` -> `go_third_party_package`

Usually, prefer these target generators. [`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) will automatically add them for you.
Usually, prefer these target generators. [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) will automatically add them for you.

Run `pants help targets` to see how the target determines what to generate. Targets for first-party code, like `resources` and `python_tests`, will generate one target for each file in their `sources` field.

Expand Down Expand Up @@ -317,7 +317,7 @@ However, we've found that it usually scales much better to use a single BUILD fi

It's useful for metadata to be as fine-grained as feasible, such as by using the `overrides` field to only change the files you need to. Fine-grained metadata is key to having smaller cache keys (resulting in more cache hits), and allows you to more accurately reflect the status of your project. We have found that using one BUILD file per directory encourages fine-grained metadata by defining the metadata adjacent to where the code lives.

[`pants tailor ::`](../../getting-started/getting-started/initial-configuration.mdx#5-generate-build-files) will automatically create targets that only apply metadata for the directory.
[`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) will automatically create targets that only apply metadata for the directory.
:::

# Parametrizing targets
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/using-pants/restricted-internet-access.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ In such cases, users are typically still able to access internal proxies and ser

## Installing Pants

The `pants` launcher from [Installing Pants](../getting-started/getting-started/installing-pants.mdx) uses GitHub Releases to download and install a PEX including Pants and all its dependencies.
The `pants` launcher from [Installing Pants](../getting-started/installing-pants.mdx) uses GitHub Releases to download and install a PEX including Pants and all its dependencies.

If you cannot access GitHub directly, you will need to follow the instructions for firewalls/restricted internet access for [the launcher itself](https://github.com/pantsbuild/scie-pants).

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/using-pants/troubleshooting-common-issues.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ For `local_store_dir` and `named_caches_dir`, you may either specify an absolute

It is safe to delete these folders to free up space.

You can also change the cache used by the `pants` script described in [Installing Pants](../getting-started/getting-started/installing-pants.mdx), which defaults to `~/.pants/cache/setup`. Either set the environment variable `PANTS_SETUP_CACHE` or change the Bash script directly where it defines `PANTS_SETUP_CACHE`. You may use an absolute path or a path relative to the build root.
You can also change the cache used by the `pants` script described in [Installing Pants](../getting-started/installing-pants.mdx), which defaults to `~/.pants/cache/setup`. Either set the environment variable `PANTS_SETUP_CACHE` or change the Bash script directly where it defines `PANTS_SETUP_CACHE`. You may use an absolute path or a path relative to the build root.

## BadZipFile error when processing Python wheels

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/using-pants/using-pants-in-ci.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ If you're using GitHub Actions to run your CI workflows, then you can use our [s
In your CI's config file, we recommend caching these directories:

- `$HOME/.cache/nce` (Linux) or `$HOME/Library/Caches/nce` (macOS)<br/>
This is the cache directory used by the [Pants launcher binary](../getting-started/getting-started/installing-pants.mdx) to cache the assets, interpreters and venvs required to run Pants itself. Cache this against the Pants version, as specified in `pants.toml`. See the [pantsbuild/example-python](https://github.com/pantsbuild/example-python/blob/main/.github/workflows/pants.yaml) repo for an example of how to generate an effective cache key for this directory in GitHub Actions.
This is the cache directory used by the [Pants launcher binary](../getting-started/installing-pants.mdx) to cache the assets, interpreters and venvs required to run Pants itself. Cache this against the Pants version, as specified in `pants.toml`. See the [pantsbuild/example-python](https://github.com/pantsbuild/example-python/blob/main/.github/workflows/pants.yaml) repo for an example of how to generate an effective cache key for this directory in GitHub Actions.
- `$HOME/.cache/pants/named_caches`<br/>
Caches used by some underlying tools. Cache this against the inputs to those tools. For the `pants.backend.python` backend, named caches are used by PEX, and therefore its inputs are your lockfiles. Again, see [pantsbuild/example-python](https://github.com/pantsbuild/example-python/blob/main/.github/workflows/pants.yaml) for an example.

Expand Down
Loading

0 comments on commit 494a90c

Please sign in to comment.