Generate API references for plugin

[Eric-Arellano]

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]

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]

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]

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 ***@***.***> 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 <#10945 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAH5UHY5BINQAPHV5RRJN5LSLT5IJANCNFSM4SNIETMA> .

[stuhood]

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]

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]

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

[obalassos]

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.