You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@karaf.apache.org by Sam Hendley <sh...@greenenergycorp.com> on 2011/05/04 18:04:15 UTC
Generating command documentation.
I really like the documentation on the karaf commands at:
http://karaf.apache.org/manual/2.1.99-SNAPSHOT/commands/commands.html
I'm assuming these were auto generated, is that tool commonly available? We
have built an application that exposes alot of shell commands and would like
to expose the help documentation. I tried searching for documentation tools
for karaf and gogo commands but I didn't come across anything obvious. Any
pointers would be much appreciated.
Thanks!
Sam Hendley
Re: Generating command documentation.
Posted by Sam Hendley <sh...@greenenergycorp.com>.
Finally got a chance to work on our docs, created a JIRA and patch.
https://issues.apache.org/jira/browse/KARAF-645
On Wed, May 4, 2011 at 2:36 PM, Jamie G. <ja...@gmail.com> wrote:
> We're always happy to receive patches. I take it the flag would be set
> to true, requiring the --help option by default? I can see how the
> --help can be an issue when making a manual. Our normal process for
> this would be to create a Jira entry at Karaf and submit a patch as an
> attachment to that issue for review.
>
> Contributing:
> http://karaf.apache.org/index/community/contributing.html
>
> Jira:
> http://issues.apache.org/jira/browse/KARAF
>
> Cheers,
> Jamie
>
> On Wed, May 4, 2011 at 3:55 PM, Sam Hendley
> <sh...@greenenergycorp.com> wrote:
> > Perfect! Thanks for the quick response. I took a look at that code and
> was
> > able to integrate it with my build system easily. It even generates docbk
> > which we were already using for documentation so it was much easier than
> I
> > was expecting.
> > The only issue I have is that adding the "--help" option to every command
> > makes the output very verbose and hides the important options in the
> noise.
> > I was looking at the source code, it looks like it would be trivial to
> add a
> > flag to disable adding that option.
> >
> https://svn.apache.org/repos/asf/karaf/trunk/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/cmdhelp/CmdHelpMojo.java
> > If I were to provide a patch to add that option and generally get the
> docbk
> > formatter up to par with the conf one would it likely be accepted?
> > Sam Hendley
> > On Wed, May 4, 2011 at 12:10 PM, Jamie G. <ja...@gmail.com>
> wrote:
> >>
> >> Have a look through the Karaf manual folder for how the it's generated:
> >> http://svn.apache.org/repos/asf/karaf/trunk/manual
> >>
> >> The project used to generate the manual is called Scalate.
> >> You can find out more about that project here:
> >> http://scalate.fusesource.org/
> >>
> >> Cheers,
> >> Jamie
> >>
> >> On Wed, May 4, 2011 at 1:34 PM, Sam Hendley
> >> <sh...@greenenergycorp.com> wrote:
> >> > I really like the documentation on the karaf commands at:
> >> > http://karaf.apache.org/manual/2.1.99-SNAPSHOT/commands/commands.html
> >> > I'm assuming these were auto generated, is that tool commonly
> available?
> >> > We
> >> > have built an application that exposes alot of shell commands and
> would
> >> > like
> >> > to expose the help documentation. I tried searching for documentation
> >> > tools
> >> > for karaf and gogo commands but I didn't come across anything obvious.
> >> > Any
> >> > pointers would be much appreciated.
> >> > Thanks!
> >> > Sam Hendley
> >
> >
>
Re: Generating command documentation.
Posted by "Jamie G." <ja...@gmail.com>.
We're always happy to receive patches. I take it the flag would be set
to true, requiring the --help option by default? I can see how the
--help can be an issue when making a manual. Our normal process for
this would be to create a Jira entry at Karaf and submit a patch as an
attachment to that issue for review.
Contributing:
http://karaf.apache.org/index/community/contributing.html
Jira:
http://issues.apache.org/jira/browse/KARAF
Cheers,
Jamie
On Wed, May 4, 2011 at 3:55 PM, Sam Hendley
<sh...@greenenergycorp.com> wrote:
> Perfect! Thanks for the quick response. I took a look at that code and was
> able to integrate it with my build system easily. It even generates docbk
> which we were already using for documentation so it was much easier than I
> was expecting.
> The only issue I have is that adding the "--help" option to every command
> makes the output very verbose and hides the important options in the noise.
> I was looking at the source code, it looks like it would be trivial to add a
> flag to disable adding that option.
> https://svn.apache.org/repos/asf/karaf/trunk/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/cmdhelp/CmdHelpMojo.java
> If I were to provide a patch to add that option and generally get the docbk
> formatter up to par with the conf one would it likely be accepted?
> Sam Hendley
> On Wed, May 4, 2011 at 12:10 PM, Jamie G. <ja...@gmail.com> wrote:
>>
>> Have a look through the Karaf manual folder for how the it's generated:
>> http://svn.apache.org/repos/asf/karaf/trunk/manual
>>
>> The project used to generate the manual is called Scalate.
>> You can find out more about that project here:
>> http://scalate.fusesource.org/
>>
>> Cheers,
>> Jamie
>>
>> On Wed, May 4, 2011 at 1:34 PM, Sam Hendley
>> <sh...@greenenergycorp.com> wrote:
>> > I really like the documentation on the karaf commands at:
>> > http://karaf.apache.org/manual/2.1.99-SNAPSHOT/commands/commands.html
>> > I'm assuming these were auto generated, is that tool commonly available?
>> > We
>> > have built an application that exposes alot of shell commands and would
>> > like
>> > to expose the help documentation. I tried searching for documentation
>> > tools
>> > for karaf and gogo commands but I didn't come across anything obvious.
>> > Any
>> > pointers would be much appreciated.
>> > Thanks!
>> > Sam Hendley
>
>
Re: Generating command documentation.
Posted by Sam Hendley <sh...@greenenergycorp.com>.
Perfect! Thanks for the quick response. I took a look at that code and was
able to integrate it with my build system easily. It even generates docbk
which we were already using for documentation so it was much easier than I
was expecting.
The only issue I have is that adding the "--help" option to every command
makes the output very verbose and hides the important options in the noise.
I was looking at the source code, it looks like it would be trivial to add a
flag to disable adding that option.
https://svn.apache.org/repos/asf/karaf/trunk/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/cmdhelp/CmdHelpMojo.java
If I were to provide a patch to add that option and generally get the docbk
formatter up to par with the conf one would it likely be
accepted?<https://svn.apache.org/repos/asf/karaf/trunk/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/cmdhelp/CmdHelpMojo.java>
Sam Hendley
On Wed, May 4, 2011 at 12:10 PM, Jamie G. <ja...@gmail.com> wrote:
> Have a look through the Karaf manual folder for how the it's generated:
> http://svn.apache.org/repos/asf/karaf/trunk/manual
>
> The project used to generate the manual is called Scalate.
> You can find out more about that project here:
> http://scalate.fusesource.org/
>
> Cheers,
> Jamie
>
> On Wed, May 4, 2011 at 1:34 PM, Sam Hendley
> <sh...@greenenergycorp.com> wrote:
> > I really like the documentation on the karaf commands at:
> > http://karaf.apache.org/manual/2.1.99-SNAPSHOT/commands/commands.html
> > I'm assuming these were auto generated, is that tool commonly available?
> We
> > have built an application that exposes alot of shell commands and would
> like
> > to expose the help documentation. I tried searching for documentation
> tools
> > for karaf and gogo commands but I didn't come across anything obvious.
> Any
> > pointers would be much appreciated.
> > Thanks!
> > Sam Hendley
>
Re: Generating command documentation.
Posted by "Jamie G." <ja...@gmail.com>.
Have a look through the Karaf manual folder for how the it's generated:
http://svn.apache.org/repos/asf/karaf/trunk/manual
The project used to generate the manual is called Scalate.
You can find out more about that project here: http://scalate.fusesource.org/
Cheers,
Jamie
On Wed, May 4, 2011 at 1:34 PM, Sam Hendley
<sh...@greenenergycorp.com> wrote:
> I really like the documentation on the karaf commands at:
> http://karaf.apache.org/manual/2.1.99-SNAPSHOT/commands/commands.html
> I'm assuming these were auto generated, is that tool commonly available? We
> have built an application that exposes alot of shell commands and would like
> to expose the help documentation. I tried searching for documentation tools
> for karaf and gogo commands but I didn't come across anything obvious. Any
> pointers would be much appreciated.
> Thanks!
> Sam Hendley