Justin Leet created METRON-1363:
-----------------------------------
Summary: Autogenerate Stellar Annotations
Key: METRON-1363
URL: https://issues.apache.org/jira/browse/METRON-1363
Project: Metron
Issue Type: Improvement
Reporter: Justin Leet
Assignee: Justin Leet
As discussed in this
[thread|https://lists.apache.org/thread.html/c6eefc77475d3aaa3feccff52399483d63bff00fadddbd31ce3f0fc8@%3Cdev.metron.apache.org%3E],
it would be nice to autogenerate the Stellar documentation we currently
maintain by hand.
A minimal POC is at https://github.com/justinleet/metron/tree/stellardoc
Considerations to be addressed
1) Consolidation across projects. Stellar functions live across projects
projects, and we should be able to consolidate all of them (without dupes)
2) Potentially abstracting generating the markdown from the actual annotation
parsing. Given that consolidation across projects might necessitate a second
pass anyway, just writing things into some format (e.g. JSON) and generating
markdown later may be nice.
3) Make sure we don't break current Javadoc.
4) Some management of this. Presumably it can be regenerated whenever and kept
in git.
Nifi apparently also does some of this, so it might be worthwhile to adapt it.
https://github.com/apache/nifi/tree/master/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation
For a bit of context, I'd looked at seeing if we could generate something
similar to actual Javadocs by piggybacking on their impl, but everything in
there is essentially considered purely internal and subject to change for any
reason.
There's also been some discussion of namespace documentation in
https://issues.apache.org/jira/browse/METRON-1361, that may affect this, but
depending on when that happens, incorporating some of that organization may be
follow-on.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
