Mark et al,
Ok, I think I hear everyone's concerns and ideas. I will challenge myself
to come up with a solution that makes everyone happy all the time.
The goals of this effort will be:
- Machine generate as much of the basic(processor description, property
description, relationship description) info as possible. This will make the
developers lives better by storing this information in one place, and make
users lives better by having the "inline" documentation match the "usage"
documentation. This will also ensure that all the documentation is formatted
consistently.
- Allow the developer to optionally provide additional html and images
that would be linked from the machine generated documentation
- Provide a way for the documentation to be generated statically and
linked from the Apache NiFi webpage
A few other 'nice-to-have' goals(probably for rev 2):
- Support documenting ControllerServices and ReportingTasks is a similar
way
-Maybe leverage existing annotations on these types? E.g @Tags,
@CapabilityDescription...
- Provide new 'documentation' annotations that would allow a developer to
describe the FlowFile attributes a processor uses on input, and which
attributes a processor modifies on output
- Provide new 'documentation' annotations that describe the expected
input format of the flow file content
- Provide new 'documentation' annotations that describe whether the
processor modifies the flow file content
- Provide new 'documentation' annotations that describe the format of the
outbound flow file content
- Provide new 'documentation' annotations that describe other NiFi
artifacts(processors, controller services, reporting tasks) that are related to
this one, e.g. "See Also ..."
- Consider if/how current Processor annotations should be displayed
(@SideEffectFree, @TriggerSerially, @TriggerWhenEmpty..., @EventDriven)
High level implementation plan:
- Develop a utility class to read an AbstractProcessor(and existing HTML
documention) and generated the basic documentation with links to existing HTML
- Integrate this class into the framework such that all documentation
displayed within a NiFi instance is generated by the utility
- Integrate this utility into something that can take a NiFi build, dig
through the nars, find the Processors/ControllerServices/ReportingTasks and
generate their appropriate HTML documentation so that it can be stored
somewhere and linked from the Apache NiFi website.
If this feels like the wrong path, or if you have any other ideas please
speak up. Thanks!
Dan Bress
Software Engineer
ONYX Consulting Services
________________________________________
From: Mark Payne <[email protected]>
Sent: Monday, January 12, 2015 3:40 PM
To: [email protected]
Subject: RE: Processor documentation plugin
Dan,
Yes, that's what I'm saying. Right now, it's all done manually by hand, and
it's a pain. The down side i think to doing it via a Maven plugin is that if
the user wants to modify it, they have to rebuild, pull the generated html out
of the target directory, and then modify it and put it in the
src/main/resources/docs. Then, if they change something they have to do this
again. If it's done on-the-fly, rather than building static content with a
plugin, that doesn't have to happen.
But you may come up with something much better than I'm envisioning :) Having a
util to do it is a good call though. Then it could be used in a maven plugin,
by the app, or wherever is most appropriate.
Thanks-Mark
> From: [email protected]
> To: [email protected]
> Subject: Re: Processor documentation plugin
> Date: Mon, 12 Jan 2015 20:34:03 +0000
>
> Mark,
> Sorry.. I missed your reply in the thread.
>
> Are you saying that going forward, you want to auto generate the doc and
> allow the developer to include a "more info" link? I wanted to confirm that
> it doesn't work that way now.
>
> I'll think about this a little more. Might write some code to generate
> the documentation from an AbstractProcessor class, then decide later where to
> integrate it(maven plugin, or somewhere else)
>
> Thanks!
>
> Dan Bress
> Software Engineer
> ONYX Consulting Services
>
> ________________________________________
> From: Mark Payne <[email protected]>
> Sent: Sunday, January 11, 2015 1:23 PM
> To: [email protected]
> Subject: Re: Processor documentation plugin
>
> Dan,
>
> Matt and I discussed this approach before but ultimately decided that we like
> the idea of just auto generating the docs on demand with a "More Info" type
> of link that lets you add more in html format if you care to do so.
>
> Others' thoughts and ideas are welcome though!
>
> Sent from my iPhone
>
> > On Jan 11, 2015, at 12:32 PM, Daniel Bress <[email protected]> wrote:
> >
> > Hi All,
> >
> > Just pulled down the code out of Git and got everything up and running on
> > Windows. This was pretty simple, and the UI looks great under chrome.
> >
> >
> > I was thinking of writing a maven plugin to generate the processor usage
> > HTML documentation.
> >
> >
> > Looking through the existing processor documentation, it seems like most
> > of this information comes directly from the code in the processors, via
> > @CapabilityDescription, and the PropertyDescriptors and Relationships.
> > Then if your processor only requires this level of documentation in the
> > HTML format, you could tie this plugin to the build, and keep your inline
> > processor documentation in sync with the HTML documentation.
> >
> >
> > What do you think?
> >
> >
> > Dan Bress
> > Software Engineer
> > ONYX Consulting Services
