I have created an inkscape diagram based on api.dia and incorporated it into the REST API
Guide DocBook XML. The updates have been committed to git. Mark, could you please rebuild
the version of guide the on the site?
Unless anyone objects, I will proceed with modifying and incorporating the other
diagrams...
David
----- Original Message -----
From: "David Jorm" <djorm(a)redhat.com>
To: "Mark McLoughlin" <markmc(a)redhat.com>
Cc: rhevm-api(a)lists.fedorahosted.org
Sent: Monday, September 20, 2010 8:27:11 PM GMT +10:00 Brisbane
Subject: Re: [rhevm-api] first diagram of RHEVM RESTful API.
----- Original Message -----
From: "Mark McLoughlin" <markmc(a)redhat.com>
To: "David Jorm" <djorm(a)redhat.com>
Cc: rhevm-api(a)lists.fedorahosted.org
Sent: Monday, September 20, 2010 8:14:09 PM GMT +10:00 Brisbane
Subject: Re: [rhevm-api] first diagram of RHEVM RESTful API.
Hi David,
On Mon, 2010-09-20 at 06:08 -0400, David Jorm wrote:
I agree, these kind of diagrams would be a good enhancement to the
official REST API Guide. The diagrams we use in the official docs are
produced using a standard set of objects in inkscape. It would only
take me a few hours to re-draw the diagrams in inkscape, and I think
that would be a worthwhile effort.
Cool.
The only thing that concerns me is keeping the diagrams up to date.
The existing PowerShell API docs are largely automatically generated
from MAML. If the API is changed, I can point my script at the new
MAML and it will modify the docbook automatically, leaving stubs where
new commands or parameters need to be described. To the greatest
extent possible, I would like to retain this capability with the new
REST and Linux API Guides.
This isn't specifically about the diagrams, right? i.e. it doesn't
insert stubs into the diagrams?
I did mean it as specifically about the diagrams, because I was (naively) assuming that we
could come up with some degree of automation for the text of the docs. For PowerShell, we
are able to do that using the MAML (Microsoft Assistance Markup Language) which comes with
each build of the API. Looking at the (fantastic!) docs you've produced so far, I can
see how the REST paradigm may not lend itself to this so easily as PowerShell did.
What you basically want is some way to track API changes so that you can
know what updates need to be made to the docs.
If we can't get any greater level of automation, then yes, we will need to institute a
Bugzilla (my preference) based process for me to be informed when docs-impacting changes
are made. I'm working on a sample inkscape-ified diagram at the moment, give me an
hour or so...
I don't think we'll be able to automate anything for that, but we could
certainly agree on a process for it - e.g. we file a trac or bugzilla
ticket against the docs whenever we make changes.
Cheers,
Mark.
_______________________________________________
rhevm-api mailing list
rhevm-api(a)lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/rhevm-api