You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Joe Brockmeier <jz...@zonker.net> on 2013/04/02 22:33:18 UTC

[ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Hi all,

So - the build process for generating API docs has changed since 4.0 ->
4.1, and it looks like in the process we've stopped generating a
"diff.txt" of APIs changed/added/deleted since the last version.

Any idea how we can generate this automagically rather than combing
through the new docs to see what's different since 4.0.x? Thanks!

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
On Wed, Apr 10, 2013, at 08:09 AM, David Nalley wrote:
> It's build-apidocs
> 
> build-docs builds the javadoc stuff, not apidocs.

/me slaps forehead. 

Thanks.

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by David Nalley <da...@gnsa.us>.
On Wed, Apr 10, 2013 at 9:04 AM, Joe Brockmeier <jz...@zonker.net> wrote:
> On Tue, Apr 9, 2013, at 12:12 PM, Alena Prokharchyk wrote:
>> I don't think it was ever a part of the Jenkins build process. I used to
>> generate the diff locally on my machine by feeding the old and new
>> version commands.xml files to the script.
>
> Hrm. I wonder what I'm doing wrong here, but I don't get commands.xml on
> 4.0.x when using "ant build-docs" - is there a different way we were
> generating API docs for 4.0.x?
>

It's build-apidocs

build-docs builds the javadoc stuff, not apidocs.

--David

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
On Tue, Apr 9, 2013, at 12:12 PM, Alena Prokharchyk wrote:
> I don't think it was ever a part of the Jenkins build process. I used to
> generate the diff locally on my machine by feeding the old and new
> version commands.xml files to the script.

Hrm. I wonder what I'm doing wrong here, but I don't get commands.xml on
4.0.x when using "ant build-docs" - is there a different way we were
generating API docs for 4.0.x?

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Jessica Tomechak <je...@gmail.com>.
On Tue, Apr 16, 2013 at 5:02 PM, David Nalley <da...@gnsa.us> wrote:

> On Tue, Apr 9, 2013 at 1:36 PM, Alena Prokharchyk <
> Alena.Prokharchyk@citrix.com> wrote:
>
> > Joe, here is the file:
> >
> > ./server/src/com/cloud/api/doc/ApiXmlDocReader.java
> >
> >
> > I used to run it this way:
> >
> > Java -cp <CS classpath> com.cloud.api.doc.ApiXmlDocReader -old <path to
> > old xml file> -new <path to new xml file> -d <diff target directory>
> >
> >
> > -Alena.
> >
> > Thanks for this - I do think that jenkins was running this at one time,
> but apparently not anymore, we should probably re-automate this, but in the
> interim, I've added directions for doing this to the wiki page:
>
>
> https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+To+Generate+CloudStack+API+Documentation
>
> --David
>

David, thanks for updating the wiki. It's very helpful.

Jessica T.

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by David Nalley <da...@gnsa.us>.
On Tue, Apr 9, 2013 at 1:36 PM, Alena Prokharchyk <
Alena.Prokharchyk@citrix.com> wrote:

> Joe, here is the file:
>
> ./server/src/com/cloud/api/doc/ApiXmlDocReader.java
>
>
> I used to run it this way:
>
> Java -cp <CS classpath> com.cloud.api.doc.ApiXmlDocReader -old <path to
> old xml file> -new <path to new xml file> -d <diff target directory>
>
>
> -Alena.
>
> Thanks for this - I do think that jenkins was running this at one time,
but apparently not anymore, we should probably re-automate this, but in the
interim, I've added directions for doing this to the wiki page:

https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+To+Generate+CloudStack+API+Documentation

--David

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Rohit Yadav <bh...@apache.org>.
In cloudmonkey I can enable the diffing and outputting when sync is done
(something like git), so when you do a sync, it can tell you stats like how
many new apis were discovered (difference of set of APIs before and after)
etc. Do we want such a feature?

Cheers.

On Tue, Apr 9, 2013 at 11:14 PM, Joe Brockmeier <jz...@zonker.net> wrote:

> Hi Alena,
>
> On Tue, Apr 9, 2013, at 12:36 PM, Alena Prokharchyk wrote:
> > Joe, here is the file:
> >
> > ./server/src/com/cloud/api/doc/ApiXmlDocReader.java
> >
> >
> > I used to run it this way:
> >
> > Java -cp <CS classpath> com.cloud.api.doc.ApiXmlDocReader -old <path to
> > old xml file> -new <path to new xml file> -d <diff target directory>
>
> Thanks! I will give that a shot.
>
> Best,
>
> jzb
> --
> Joe Brockmeier
> jzb@zonker.net
> Twitter: @jzb
> http://www.dissociatedpress.net/
>

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
Hi Alena, 

On Tue, Apr 9, 2013, at 12:36 PM, Alena Prokharchyk wrote:
> Joe, here is the file:
> 
> ./server/src/com/cloud/api/doc/ApiXmlDocReader.java
> 
> 
> I used to run it this way:
> 
> Java -cp <CS classpath> com.cloud.api.doc.ApiXmlDocReader -old <path to
> old xml file> -new <path to new xml file> -d <diff target directory>

Thanks! I will give that a shot. 

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Alena Prokharchyk <Al...@citrix.com>.
Joe, here is the file:

./server/src/com/cloud/api/doc/ApiXmlDocReader.java


I used to run it this way:

Java -cp <CS classpath> com.cloud.api.doc.ApiXmlDocReader -old <path to
old xml file> -new <path to new xml file> -d <diff target directory>


-Alena.


On 4/9/13 10:27 AM, "Joe Brockmeier" <jz...@zonker.net> wrote:

>On Tue, Apr 9, 2013, at 12:12 PM, Alena Prokharchyk wrote:
>> I don't think it was ever a part of the Jenkins build process. I used to
>> generate the diff locally on my machine by feeding the old and new
>> version commands.xml files to the script.
>
>Sorry, which script?
>
>Best,
>
>jzb
>-- 
>Joe Brockmeier
>jzb@zonker.net
>Twitter: @jzb
>http://www.dissociatedpress.net/
>

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
On Tue, Apr 9, 2013, at 12:12 PM, Alena Prokharchyk wrote:
> I don't think it was ever a part of the Jenkins build process. I used to
> generate the diff locally on my machine by feeding the old and new
> version commands.xml files to the script.

Sorry, which script?

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Alena Prokharchyk <Al...@citrix.com>.
I don't think it was ever a part of the Jenkins build process. I used to
generate the diff locally on my machine by feeding the old and new version
commands.xml files to the script.

We can generate this automatically using 2 ways:

1) Using @Since annotation for new parameters/commands. As a part of the
build process, extract all the commands having @Since="current version"
and put them into diff file. The annotation is already in place, but I
believe most of the times people forget to update it for new
commands/parameters they've been adding.

2) By keeping commands.xml of the previous version in the code base. As a
part of the build process, generate the diff between version (n=current
version) commands.xml and version (n-1).

-Alena.


On 4/5/13 9:31 AM, "Joe Brockmeier" <jz...@zonker.net> wrote:

>Bumping this. Any ideas?
>
>On Tue, Apr 2, 2013, at 03:33 PM, Joe Brockmeier wrote:
>> Hi all,
>> 
>> So - the build process for generating API docs has changed since 4.0 ->
>> 4.1, and it looks like in the process we've stopped generating a
>> "diff.txt" of APIs changed/added/deleted since the last version.
>> 
>> Any idea how we can generate this automagically rather than combing
>> through the new docs to see what's different since 4.0.x? Thanks!
>> 
>> Best,
>> 
>> jzb
>> -- 
>> Joe Brockmeier
>> jzb@zonker.net
>> Twitter: @jzb
>> http://www.dissociatedpress.net/
>
>
>Best,
>
>jzb
>-- 
>Joe Brockmeier
>jzb@zonker.net
>Twitter: @jzb
>http://www.dissociatedpress.net/
>

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
On Tue, Apr 9, 2013, at 12:05 PM, Chiradeep Vittal wrote:
> I believe this was never automated.
> The apidocs generation tool generates an XML document that contains all
> the APIs.
> (tools/apidoc/target/commands.xml). We can diff the 4.0 xml and the 4.1
> xml using a tool such as xmldiff (https://pypi.python.org/pypi/xmldiff).

This is helpful, thanks!

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Chiradeep Vittal <Ch...@citrix.com>.
I believe this was never automated.
The apidocs generation tool generates an XML document that contains all
the APIs.
(tools/apidoc/target/commands.xml). We can diff the 4.0 xml and the 4.1
xml using a tool such as xmldiff (https://pypi.python.org/pypi/xmldiff).

I tried this, but it hangs. The man page for xmldiff says:
"xmldiff uses an algorithm with a (too) high algorithmical complexity,
which
makes it unsuitable to process large XML documents. If your document
has more than about 100 nodes, you should probably look for an
alternative solution"

On 4/5/13 9:31 AM, "Joe Brockmeier" <jz...@zonker.net> wrote:

>Bumping this. Any ideas?
>
>On Tue, Apr 2, 2013, at 03:33 PM, Joe Brockmeier wrote:
>> Hi all,
>> 
>> So - the build process for generating API docs has changed since 4.0 ->
>> 4.1, and it looks like in the process we've stopped generating a
>> "diff.txt" of APIs changed/added/deleted since the last version.
>> 
>> Any idea how we can generate this automagically rather than combing
>> through the new docs to see what's different since 4.0.x? Thanks!
>> 
>> Best,
>> 
>> jzb
>> -- 
>> Joe Brockmeier
>> jzb@zonker.net
>> Twitter: @jzb
>> http://www.dissociatedpress.net/
>
>
>Best,
>
>jzb
>-- 
>Joe Brockmeier
>jzb@zonker.net
>Twitter: @jzb
>http://www.dissociatedpress.net/

Re: [ACS41][DOCS] Generate diff of APIs changed/added/deleted?

Posted by Joe Brockmeier <jz...@zonker.net>.
Bumping this. Any ideas? 

On Tue, Apr 2, 2013, at 03:33 PM, Joe Brockmeier wrote:
> Hi all,
> 
> So - the build process for generating API docs has changed since 4.0 ->
> 4.1, and it looks like in the process we've stopped generating a
> "diff.txt" of APIs changed/added/deleted since the last version.
> 
> Any idea how we can generate this automagically rather than combing
> through the new docs to see what's different since 4.0.x? Thanks!
> 
> Best,
> 
> jzb
> -- 
> Joe Brockmeier
> jzb@zonker.net
> Twitter: @jzb
> http://www.dissociatedpress.net/


Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/