A need for more Documentation

jake-arkinstall commented 3 years ago

At present, the documentation for dbx_build_tools is very minimal: it provides a "lightning tour" - which is no substitute for more detailed documentation that people might need when they get beyond the "hello world" stage.

This is a shame, because dbx_build_tools is the best option for a hermetic bazel python build, which makes it a better candidate than rules_python for anyone who takes hermeticity seriously. Without a more detailed README, it's hard to get to grips with, and I wonder if this means that it attracts a smaller userbase than it might otherwise do.

For example, things I'd like to know as a brand new user:

Do I need to use bzl? It seems to be a feature, rather than a requirement - and bringing in a new workflow that will only impact the (relatively small) python component of my project isn't attractive to me.
How can I resolve problems when packages cannot be found? (right now I can't get any imports to work with bzl gen, and I don't have anywhere to look - my debug stage so far involves looking through the dbx_build_tools repo, messing around with dbx_py_pypi_piplib in a BUILD file rather than BUILD.in, and generally chasing my tail).
I just want to focus on python3, with python2 hitting EOL over a year ago. But register_toolchains seems to need a python2.7 toolchain as well as the python3.8 toolchain that I want - why?

The documentation doesn't need to go into such details, but as things stand, it seems that such a clearly useful and well-thought-out project is being let down by the documentation. Once I get to grips with using the project I'd be happy to help on that front.

joshua-cannon-techlabs commented 2 years ago

Can I second this? Very heavily, too. Poking around the code shows there's a lot of depth (import validation, mypy aspect, code coverage support)

These are features I'd love to experiment with and use, but fear if they aren't documented then they are not part of the public API. Or they'll be a pain to understand how they should be used.

jsharpe commented 2 years ago

@joshua-cannon-techlabs mypy is missing some of the code for it to be functional: #6. Code coverage is controlled by "@dbx_build_tools//build_tools:coverage-enabled": https://github.com/dropbox/dbx_build_tools/blob/1a0fe35a39b874d32f52a7e73d75d37be3115782/build_tools/py/cfg.bzl#L14 which is enabled by --define collect_code_coverage=true: https://github.com/dropbox/dbx_build_tools/blob/1a0fe35a39b874d32f52a7e73d75d37be3115782/build_tools/BUILD#L210-L215

joshua-cannon-techlabs commented 2 years ago

Right, it'd be nice if these things were documented closer to the source or the public README than a GitHub issue comment ;)

jsharpe commented 2 years ago

Agreed; I've had to ask dropbox employees via slack for tips on how to use these rules but in the end I mostly end up just having to read the source to work out how they all work. I guess it comes down to there being little business value to dropbox to actually provide more complete documentation.

joshua-cannon-techlabs commented 2 years ago

Yeah, I'm a source-reader myself, but I wouldn't say it's my preferred method of consumption :sweat_smile:

I'd say it's probably in the same business-value boat as open-sourcing the rules to begin with. Contributing back to the community and garnering good PR from it :smile:

jhance commented 2 years ago

Well, the "just want to focus on python3" bit is solved now. bzl is not necessary but it is useful if you want to use our python generator.

The import validation can be ran as this:

bazel build --aspects=build_tools/py/bazel_validation/import_validation.bzl%dbx_py_validate_imports --output_groups=py_import_validation_files

A good easy PR would be to add a tool like bzl tool //tools:py-import-validate ... that runs this for you. I would rather not expose the exact command for the starlark in the documentation as a public API, but a tool would be great.

The mypy aspect is not usable publicly and I'm working on fixing it and will document that when it is ready.

jhance commented 2 years ago

We have an internal "example repository" that we use to validate that the open source equivalent of our build rules will continue to work.

I got approvement from legal team to make this example repository open source, so we can have it serve as both validation and examples. Once I get the mypy stuff working (which I am almost dont with, but encountering some odd bug with our custom plugins while trying to move them to the toolchain) I will add examples there too.

As far as business value goes, this project is open source mostly because the people who worked on it wanted this to be publicly available more so than the business did (it was a product of hackweek). While I don't mind adding docs this is a project I work on in my free time at work more so than I am paid to do it :)

joshua-cannon-techlabs commented 2 years ago

FWIW We've migrated from Bazel and the Python rules to https://www.pantsbuild.org/ which seemingly supports Python a lot more... natively.

jhance commented 2 years ago

Pants doesn't support a hermetically source built python so I'm not sure I would say it supports it natively. Its support is more similar to bazel upstream than these rules as far as I can tell.

ewhauser commented 2 years ago

@jhance Just wanted to drop a note and say I appreciate the effort! Definitely looking forward to seeing the example repo with a working mypy example.

JRodDynamite commented 1 year ago

Any kind of update available on this? Is there a chance of this happening? 😅

jsharpe commented 1 year ago

I very much doubt it at this point; the process of keeping this repo up to date seems to have stalled as there are no recent updates to it. @jhance care to comment on the state of this repo?

dropbox / dbx_build_tools

A need for more Documentation #27