dropbox / dropbox/dbx_build_tools

A need for more Documentation

Open
#27 12 comments 1 reaction 0 assignees View on GitHub
Dominant language
Go
Stars
209
Forks
34
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.