Also a couple of observations: - Y'all have been h...
# general
Also a couple of observations: • Y'all have been hitting the Rust pipe hard. It really shows in the design of the Rules API. I'm loosely into Rust, so I think this is kinda cool, but there are ways it seems a bit non-pythonic. I'll try to develop this into more concrete suggestions, but most of what I mean is having to import lots of little datatypes to use the API, when maybe having some sensible factory functions around that would be smoother. Like I said, I'll try to keep working with this and then I could make some proposals once I work through the kinks a bit more. • Having just plain-jain API docs built from the docstrings in the code would be useful. This should be as simple as telling sphinx to generate it. Y'all have put a lot of work into writing comprehensive documentation, but some of the best documentation is buried in the code and not published on the internet (at least not where I can see it easily).
(1) the rules API is intended to make it safe to express complex build logic in a cacheable way. the way we have currently accomplished this is by codifying each disparate build step that can be independently cached with its own hashable type, e.g. a dataclass. the intent of the rules API however is that you should not have to import a ton of small things, and instead you should be able to make use of higher-level wrappers. the rules API allows you to wrap complex actions into a series of cacheable `@rule`s, which you can then consume without much difficulty. we are 1000% working on building more of those higher-level wrappers (so your concern is a 100% correct observation), but i would also encourage you to consider whether a set of `@rule`s that would allow you to do e.g.
Copy code
await Get(BuiltDockerImage, DockerInput(...))
might accomplish the goal you have with factory functions. anything that requires a process execution for sure we want to have in a ruleset so it can be cached, for example. we would really love 100% to hear your thoughts on ergonomics though, and it sounds like you're barking up exactly the right tree. please feel free to elaborate in an issue, or slack (we mostly use the #engine channel for this)
(2) i agree, and created this issue a while ago ( i am not familiar with the discussion that led to the choice to use nor whether it can easily be exported. see my thread here -- i share your concern that it may make it more confusing to contribute to docs.