Dan, Having the docs available for the apache site is a great point. We'd definitely want to be able to have them there.
Thanks Joe On Sun, Jan 11, 2015 at 1:58 PM, Daniel Bress <[email protected]> wrote: > Joe, > Thanks for welcoming and feedback. I'm definitely looking forward to > learning from and contributing to Apache NiFi. > > I think a good thing about having statically generated content is it > could be linked from the website(https://nifi.incubator.apache.org/)? > E.g. these are the processors in the build 0.0.1, and this is how you use > them. Don't you think you'd want that documentation generated with the > build and linked from the website at that point? > > As far as people providing their own documentation... yeah that needs to > be sorted. I was thinking maybe the docs could be modified to have a > generated section that pulls as much as it can from the code, then have a > user definable section should that processor require more a more in depth > explanation. > > Dan Bress > Software Engineer > ONYX Consulting Services > > ________________________________________ > From: Joe Witt <[email protected]> > Sent: Sunday, January 11, 2015 1:30 PM > To: [email protected] > Subject: Re: Processor documentation plugin > > Dan, > > First, very happy to see you're planning to contribute. > > So this is a great idea! > > A few things to consider here: > - At what point in the application lifecycle to create automatic > processor/extension documentation > 1) Build phase: Best done via a Maven plugin probably. > 2) Startup Phase: Could be part of the nar loading/extension service > provider hunt. > 3) On demand: As a request comes to view-usage or look at the extension > listing generate the processor/extension docs. > > Given that it would likely be purely static content any of these approaches > are reasonable. My estimation then is that the ease of implementation in > order is 3, 2, 1. So you might consider approaching this that way. Do > option 3 since that code would be reusable. If we find that isn't good > enough then go option 2. If we think we need earliest possible binding > then option 3. We can just grow through it if needed. But KISS probably > points at 3 in my opinion. > > Also as Benson pointed out in another thread we're likely heading down the > path of having a separate Git repo for Maven specific plugins/archetypes. > So you might want to hold off on the maven part specifically until that > stabilizes too. > > Consideration for the generation beyond (when): > - What if the developer already supplies processor docs? Perhaps > auto-generation only kicks in if they've not done this. Or maybe we > provide both (auto generated and developer generated)...something to thing > about. > > Very cool that you're wanting to take a stab at this. I think it will be > really helpful and it ensures maximum bang for the buck on those > annotations for users. > > Thanks! > Joe > > On Sun, Jan 11, 2015 at 1:23 PM, Mark Payne <[email protected]> wrote: > > > 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 > > >
