pantsbuild / pants

The Pants Build System

https://www.pantsbuild.org

Apache License 2.0

3.35k stars 640 forks source link

Generate API references for plugin #10945

Open Eric-Arellano opened 4 years ago

Eric-Arellano commented 4 years ago

When we do this, we should probably rewrite the docs. Right now, they have too much of a reference style, but with lots of prose. Instead, the reference should live in a dedicated reference section, so that the main docs can focus more on concepts + tutorials + how tos.

jriddy commented 4 years ago

I second this. Honestly, sphinx-based automated documentation of the docstrings you guys already put in the code would make developing plugins much easier.

Right now I read the code to find the docstrings. I'd rather search a website and click links since it's usually faster to navigate.

Eric-Arellano commented 4 years ago

Definitely agreed, and thanks for the feedback.

I don't have much experience with Sphinx (and sorry for being lazy not searching myself) - do you know if it's possible to indicate which directories are valid to generate docs for? We want, for example, to generate engine/, but not engine/internals. And there may be certain things in engine/ that we want to leave off too.

jriddy commented 4 years ago

Yes and if I remember correctly this generation is more opt-in than opt-out, so it's pretty easy to tailor this.

I can perhaps help with this later this week or this weekend

On Mon, Oct 19, 2020, 23:07 Eric Arellano notifications@github.com wrote:

Definitely agreed, and thanks for the feedback.

I don't have much experience with Sphinx (and sorry for being lazy not searching myself) - do you know if it's possible to indicate which directories are valid to generate docs for? We want, for example, to generate engine/, but not engine/internals. And there may be certain things in engine/ that we want to leave off too.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/pantsbuild/pants/issues/10945#issuecomment-712559333, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAH5UHY5BINQAPHV5RRJN5LSLT5IJANCNFSM4SNIETMA .

stuhood commented 4 years ago

I also expect that generating an explicit list of all @unions would be helpful, since they directly represent all of the places where plugins can add logic.

tdyas commented 4 years ago

Ideas from an internal Toolchain discussion that I had with @Eric-Arellano:

The engine invokes rules in "chains" of method calls as it goes from a set of input types to an output type A useful type of reference would show the signatures of "standard" rules like goal rules with the types hyperlinked to other rules. (It could be nice to navigate in the reference up and down method chains for different use cases.)
Show all Union types and link to the various Union's with reference explanation as to what the Union is used for and a link to an appropriate tutorial. These are the "built-in extension points" so good to document them.
Generate references programmatically and upload to Readme.com

stuhood commented 2 years ago

14081 took a first step in this direction. Thanks @kaos!

obalassos commented 2 years ago

Second everything in this thread. Just completed my first semi-functional plugin and the biggest pain points are trying to navigate the rule chains. Being able to to navigate from a goal_rule to it's required input and output and unions, and then following down each is definitely a must if you want people to be able to write their own plugins without reinventing the wheel.

The only thing I might add is one of the hardest parts for me to grok was trying to understand how to go from a given input to a given output. As an example I ended up with a DigestEntries with paths I wanted to change and then turn the whole thing into a single Digest.

At the moment the only way to write plugins is to read a LOT of code and work your way backwards and hope you didn't miss an already written function/rule.