Dan These ideas are interesting. The notion of embedded templates and documentation to ease the onboarding process of learning new processors is great. Where I am conflicted though is the idea of how best to expose Nars to the user facing application. We'll probably end up doing that anyway but I thinking leading that up with the Nar documentation might just create more confusion. The nars were about allowing developers to provide extensions with the comfort of what classloader isolation gave them. What is proposed here is about more than documentation of course. It is about how to make Nar's a first class concept all the way up to/through the user experience. There is a lot more we need to consider there I think before we tackle the documentation aspects of nars more. Perhaps this is a good candidate to start a design proposal in wiki/confuence so it can be drawn out and more readily commented on that in email.
Thanks Joe On Sat, Jun 27, 2015 at 3:44 PM, Dan Bress <[email protected]> wrote: > All, > > Two tickets Bob Mills wrote [1] [2] got me thinking about some cool new > things we could possibly do with nars. Wanted to put the ideas to the group, > get some feedback, and if positive create tickets. > > > One of Bob's tickets asked for a way for a user to provide "top level" > documentation like "User Guide" "Expression Language Guide" "Admin Guide", > and the other asks for a way to expose the version number of a nar in the UI > somewhere. I'm wondering if his first idea could be modified to be "a nar > should be able to provide highlevel documentation about it's self" > > > I would propose the following features be added to nars, and how they are > presented inside the application. > > > 1) As discussed in NIFI-666, allow a nar to specify its version, provider, > provider url > > 2) Update the generated component documentation such that the top of each > page has a breadcrumb that could look something like: > nar-name-version/type/component-name > > Where type could be Processor, ControllerService or ReportingTask > > 3) Allow a nar to contain a "docs" folder containing html documents. This > provides a place for a nar to provide documentation about it's self. This > would allow an XML nar to describe XPath and XSLT. A database nar could > describe SQL. etc. > > 4) Show nars themselves in the "NiFi Documentation" page, where clicking > on a nar shows you all the metadata in (1), the documentation described in > (3), links to all the component documentation contained in that nar, and a > tree of the other nars this nar depends on > > 5) Change NiFi documentation to support two views. > > a) group by type. This is the current view. groups all Processors, > ControllerServices and ReportingTasks together. > > b) group by nar. This is a new view that would group by nar at the > top level, then underneath each nar would show the Processors, > ControllerServices and Reporting tasks it contains. > > 7) Add a "templates" directory in a nar, where a user can include prebuilt > NiFi xml templates in their nar. Automatically load these templates into the > templates list when the nar is in the nar directory. > > > > What does everyone think? > > > > > > [1] > https://issues.apache.org/jira/browse/NIFI-66<https://issues.apache.org/jira/browse/NIFI-667>6 > > [2] https://issues.apache.org/jira/browse/NIFI-667 > > > Dan Bress > Software Engineer > ONYX Consulting Services
