Re: [Xen-API] improving the XenAPI docs

[Rob Hoes <Rob.Hoes@xxxxxxxxxx>]

I quite like these ideas for improving the XenAPI docs. I think adding tags to 
the fields and functions so they can be logically grouped is a good idea. We 
have recently started collecting some docs about the use of the XenAPI on 
xapi-project.github.io, and have pages for several topics, e.g. 
http://xapi-project.github.io/xen-api/snapshots.html for snapshots. I think 
that it is useful to have such topic-level docs to tie things together (with 
examples) next to descriptions of individual fields and functions. Perhaps we 
could start by simply augmenting topic pages with an (automatically generated 
from tags) overview of relevant XenAPI fields and functions, at the bottom of 
the page or in a sidebar?

Regarding Dave's second point, it would definitely be better to write more 
detailed descriptions of the XenAPI fields/functions (including code examples 
and details on the keys/values of map types!!) in something like markdown 
outside the IDL source code, and integrate these transparently with the 
existing docs.

Currently, the web-based XenAPI reference at 
http://xapi-project.github.io/xen-api/ is rendered on the client side by 
javascript from a JSON description of the XenAPI that comes straight from the 
IDL. We probably need to switch to a more server side approach to integrate 
markdown fragments, and the Jekyll stuff from github (which we already use on 
xapi-project.github.io) may be able to do this. However, the last time I tried 
it, the IDL JSON file seemed  a little too complex for Jekyll to process, so 
perhaps we need to generate something slightly more straightforward from the 
IDL.

I'll see if I can knock up a quick prototype.

Cheers,
Rob

> -----Original Message-----
> From: xs-devel-request@xxxxxxxxxxxxxxxxxxx [mailto:xs-devel-
> request@xxxxxxxxxxxxxxxxxxx] On Behalf Of Dave Scott
> Sent: 27 January 2015 9:03 PM
> To: xen-api@xxxxxxxxxxxxxxxxxxxx
> Cc: xs-devel
> Subject: [xs-devel] improving the XenAPI docs
> 
> Hi,
> 
> Iâve been thinking about how to improve the XenAPI reference[1]. The
> things I like about the reference are:
> 
> - itâs generated from the IDL, so itâs always up to date
> - itâs got everything in it
> 
> The things I donât like about the reference are:
> 
> - itâs got everything in itâ in alphabetical order, rather than in any
> kind of usefulness order
> - the descriptions of fields/ functions areâ terse (and often tautologous)
> - there are no in-line examples
> 
> Iâd like to improve the reference by making 2 extensions:
> 
> 1. Iâd like to add tags to each field and function, and allow the docs to
> be searched by tag (e.g. find all the fields and functions related to
> âsnapshotsâ) A well-known tag name would be âcoreâ meaning âstuff you need
> to knowâ and I propose we either filter for that by default, or at least
> re-order the elements so we have core first.
> 
> 2. Iâd like to create a sparse file overlay per-API in the xen-api repo.
> An overlay file â if it exists â would override whatever terse description
> exists in the raw IDL. The overlay would be written in markdown and would
> contain paragraphs of description, links and example usages. It would be
> easy to add an overlay to the repo without breaking the build (i.e.
> thereâs no need to keep all the docs inside the code as well-quoted
> strings where you have to satisfy the compiler).
> 
> Thoughts/ suggestions/ improvements welcome!
> 
> Cheers,
> Dave
> 
> [1] Thereâs more than one copy on the web, but hereâs the one I was
> looking at: http://xapi-project.github.io/xen-api/index.html
_______________________________________________
Xen-api mailing list
Xen-api@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api