Documentation re-arrangement #65
Conversation
| final String tagArg = "DYNAMIC_SPOUT_CONFIGURATION"; | ||
| final List<ClassSpec> classSpecs = new ArrayList<>(); | ||
| classSpecs.add(new ClassSpec(SpoutConfig.class, SpoutConfig.setDefaults(Maps.newHashMap()))); | ||
| classSpecs.add(new ClassSpec(KafkaConsumerConfig.class)); |
There was a problem hiding this comment.
once KafkaConsumer bits get moved out to its own namespace, we'll create its own "DocTask" and remove it from being generated here.
script/generateDocs.sh
Outdated
| #!/bin/bash | ||
|
|
||
| ## Build package | ||
| mvn package -DskipTests=true |
There was a problem hiding this comment.
Why not turn this into a mvn goal or something?
There was a problem hiding this comment.
Yea thought about that. We could call out to this, or add a bunch of goals for each config type, dunno which is better
There was a problem hiding this comment.
I would do one goal in the root POM that takes a comma delimited list of classes or something like that. That way it's injected at that base POM.
There was a problem hiding this comment.
Hooked this into the site goal. IE mvn clean site
Didn't feel like its worth running on every compile
| /** | ||
| * Define a Class instance to generate documentation from. | ||
| */ | ||
| public class ClassSpec { |
There was a problem hiding this comment.
This seems unnecessary to me. Why not just force the classes that we want to generate docs for to use an interface that includes a setDefaults/getDefaults method?
There was a problem hiding this comment.
I was just trying to change as little as possible for a first pass. I think we need to think about how/what things like SpoutConfig actually look like
There was a problem hiding this comment.
^-- as part of a larger work item review those and come up with a plan
There was a problem hiding this comment.
Yeah I dig ya, I just feel like adding an interface that's like DefaultableConfig or something would be cleaner on the implementation.
There was a problem hiding this comment.
I agree. I think we need to come up with concrete config classes instead of maps, and add that as part of it.
There was a problem hiding this comment.
Going to create a follow up issue to create concrete config classes for DynamicSpout, SidelineSpout (if needed), and KafkaConsumer.
There was a problem hiding this comment.
I looked at adding an interface but currently we use static methods to setDefaults(). So before we could apply an interface over it, we'd first need to refactor SpoutConfig / SidelineConfig into being instantiated into an instance.
I think this is better pushed off to the specific issue/work around configs, see #80
|
So this isn't the 100% cleanest/DRY solution, but I think it satisfies what I was going for. Removing the cross-package pollution, with now adding hooks for generating metric docs. The README as a whole needs an overhaul ( see #8 ) but we're in a better spot than we were before the PR. I also believe how we deal w/ Configs also needs some re-tooling ( #80 ) |
Looking at #19 one of the required changes is how we generate our docs. Currently the generator pulls in dependencies across what will become separate modules.
This PR moves the Doc generating logic out, and allows each "module" to call the generator passing in the bits it needs to build its documentation.