docs: there may be multiple BUILD files in a directory

[AlexTereshenkov]

Docs rendered locally:

[AlexTereshenkov]

Link tested.

[kaos]

For instance, you could store source code targets and
macros in different files to have better separation of concerns

The example seems to show having different targets in the files, which works fine, but the above text talks about macros, and that will not work. The files are not merged before parsing, so if you decalare a def my_macro(): ... in one, you can't call it from the other.

[kaos]

That is, they're parsed, and processed, individually, they will just share "namespace" for their respective targets, so they show up together..

[AlexTereshenkov]

Thanks, Andreas! Perhaps bringing macros into this wasn't worth it. I've updated the docs to use files and code targets; this should keep things simple.

[huonw]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

A couple of questions:

1. Do you use this in practice?
2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?

[kaos]

Thanks for improving the documentation! I think that we should be careful with how we phrase this: I think that for most users, having everything in one BUILD file works best, and trying to split an individual file up is likely to just cause confusion. It seems reasonable to describe that it is possible, though.

I agree with ☝🏽

A couple of questions:

1. Do you use this in practice?

See this thread: https://chat.pantsbuild.org/t/16949338/is-there-a-way-to-exclude-an-arbitrary-build-target-at-runti#45196675-a2bb-4472-a837-e4de911f6898

2. The BUILD.experimental example sounds good; maybe we could use that as the only example?
3. Maybe we could also add an info/warning box that explicitly suggests that "one BUILD is usually what you want", too?