search

eidolon-ai / eidolon

The first AI Agent Server, Eidolon is a pluggable Agent SDK and enterprise ready, deployment server for Agentic applications
https://www.eidolonai.com/
Apache License 2.0
286 stars 30 forks source link

[ docs ] add a note to builtin components docs explaining that + means required #803

Open flynntsang opened 1 month ago

flynntsang commented 1 month ago

See comment 2024-10-01

Problem: In the tables at the top of builtins documentation, it's not obvious why some properties are preceded with + and other by -.

To do:

Example:

Image

LukeLalor commented 1 month ago

This is generated by "json schema for humans" in docbuilder.py

Note, we could also consider

  1. making our own markdown template
  2. using the html generator instead
LukeLalor commented 1 month ago

throwing the needs more info tag on to decide how deeply we want to refactor our auto docs since right now they kinda suck

flynntsang commented 1 month ago

Update: let's not gold-plate the request if we don't need to. If it's simple enough to append a note on each generated page that [ + ] indicates required we're good for now. The objective at the moment is to make the page is more readily understandable to the person reading the page.

LukeLalor commented 1 month ago

I looked into this some today. We will need to monkey patch MarkdownTemplate.properties_table to customize the table behavior. This is possible, but isn't great. I would suggest that the tech debt here is not worth the slight inconvenience of learning the + / - syntax. Otherwise the proper way to handle this would be to submit a pr to json schema for humans that adds some configuration around this option, but that is more work.

Perhaps we the better option would be to fork the dependency, make the change locally and use our branch. Then swap back over to json schema for humans when they get our change in. This process would be a bit of work, but is how we would avoid taking on tech debt here.

flynntsang commented 1 month ago

Is it possible to leave the table behavior alone, but change the page behavior?

Specifically, add a note on the page, above the table:

"Required attributes are marked with +"

If possible to do, that would meet the user story requirement.

On Fri, Oct 4, 2024, 6:15 AM Luke Lalor @.***> wrote:

I looked into this some today. We will need to monkey patch MarkdownTemplate.properties_table to customize the table behavior. This is possible, but isn't great. I would suggest that the tech debt here is not worth the slight inconvenience of learning the + / - syntax. Otherwise the proper way to handle this would be to submit a pr to json schema for humans that adds some configuration around this option, but that is more work.

Perhaps we the better option would be to fork the dependency, make the change locally and use our branch. Then swap back over to json schema for humans when they get our change in. This process would be a bit of work, but is how we would avoid taking on tech debt here.

— Reply to this email directly, view it on GitHub https://github.com/eidolon-ai/eidolon/issues/803#issuecomment-2393355810, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACS2HZ3TDWEG2WHWIVB6JQTZZZTEZAVCNFSM6AAAAABOZGGQGOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJTGM2TKOBRGA . You are receiving this because you authored the thread.Message ID: @.***>

LukeLalor commented 1 month ago

yes, we can add that to the template above the table without complexity

flynntsang commented 1 month ago

Perfect

On Fri, Oct 4, 2024, 10:39 AM Luke Lalor @.***> wrote:

yes, we can add that to the template above the table without complexity

— Reply to this email directly, view it on GitHub https://github.com/eidolon-ai/eidolon/issues/803#issuecomment-2393868352, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACS2HZ2KB36E5A7YOFFQQZLZZ2SDNAVCNFSM6AAAAABOZGGQGOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJTHA3DQMZVGI . You are receiving this because you authored the thread.Message ID: @.***>