New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide FieldAction description via /fieldActions service #173

Open
igarashitm opened this Issue Dec 8, 2017 · 8 comments

Comments

Projects
None yet
4 participants
@igarashitm
Copy link
Member

igarashitm commented Dec 8, 2017

Provide FieldAction description via /fieldActions REST service. Involves

  • Add displayName and description into @AtlasFieldActionInfo
  • Add displayName and description into @AtlasFieldActionParameter (#536)
  • Add those into FieldAction model to deliver to UI
  • Use those metadata in UI

This one is used in UI to show a detail of FieldAction. One option would be to show a tooltip with Summary, and have a detailed explanation in the separated page, linked from the tooltip. It depends on how long the description could be.

@igarashitm

This comment has been minimized.

Copy link
Member Author

igarashitm commented Dec 8, 2017

Hi @jpav , can you look at this? as you already wrote field action README, it's already in halfway right?

@jpav

This comment has been minimized.

Copy link
Contributor

jpav commented Dec 8, 2017

I've added quite a few new actions, so halfway might be a stretch :-), but sure, I'll look into this.

@igarashitm

This comment has been minimized.

Copy link
Member Author

igarashitm commented Dec 8, 2017

The annotation parameter might not fit well with the descriptions, if it's longer and/or structured. Having .md file and take it up when packing a model object would be yet another option.

Also, we have some concerns around the TypeConverter, and possibly we want to provide them to the UI to display, apart from validation doing today. If so, we might want to have some unified store (like .md) and common utility to take it up and push into the model returning to UI.

@mattrpav , @rohanmars do you have any idea around returning some conversion concerns to the UI? I don't yet have any idea when/where to show, as TypeConverter is automatic thing unlike FieldAction.

@mattrpav

This comment has been minimized.

Copy link
Member

mattrpav commented Dec 8, 2017

+1 I agree w/ the approach you suggest.. provide some standard way to feed .md files (perhaps using classpath getResource()?) to the UI and have an agreed upon set of supported markups-- headers, bullet list items, hyper link, etc). I don't suspect the information would need to change between builds, so it feels safe to package in the jars.

@igarashitm

This comment has been minimized.

Copy link
Member Author

igarashitm commented Dec 8, 2017

Yep, it's kinda balance between

  • Having document within the code (sync++, easy to find the doc needs to be updated when code)
  • Separate document with structured format (expression++, better for longer and structured)

And please keep in mind, we can consider auto-generate the .md from annotation for the readable offline document. We can focus on UI online one to judge this.

@igarashitm

This comment has been minimized.

Copy link
Member Author

igarashitm commented Dec 8, 2017

Apache Camel is doing it greatly, having some annotations for documenting, which are taken up and embed generated markdown texts into .md file in the middle of the build.
https://github.com/apache/camel/blob/master/camel-core/src/main/java/org/apache/camel/component/bean/BeanEndpoint.java
https://github.com/apache/camel/blob/master/camel-core/src/main/docs/bean-component.adoc

@mattrpav

This comment has been minimized.

Copy link
Member

mattrpav commented Dec 19, 2017

@igarashitm looks like Camel is using AsciiDocs for the detailed description and the ticket notes are mentioning Markdown.

I think we could enrich the FieldAction metadata object that returns via the REST service. It could combine the annotation data + the markdown/asciidoc data. If that sounds good, we could get started and work until the following questions are addressed:

  1. What format for the detail description doc? asciidoc or markdown?

  2. Where do we want to store them? atlas-core/src/main/resources?

  3. Who is going to provide the copy for the the text in the document?

@jpav jpav removed the target/tp4 label Mar 28, 2018

@igarashitm igarashitm added the group/ui label Apr 12, 2018

@jpav jpav removed their assignment Jul 13, 2018

@deernano deernano added the prio/p0 label Aug 7, 2018

@igarashitm

This comment has been minimized.

Copy link
Member Author

igarashitm commented Feb 21, 2019

transformation description shouldn't be that long and would be fine sitting in annotation. Just add a description property on AtlasFieldActionInfo and generate a table in the docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment