[openstack-dev] [api] APIs schema consumption discussion

Graham Hayes gr at ham.ie
Thu Jan 4 16:36:57 UTC 2018

On 22/11/17 20:04, Graham Hayes wrote:


> When I was talking to Gil about it, I suggested writing a new sphinx /
> docutils formatter. I am not sure how feasible it would be, but it could
> be possible (as sphinx has the whole page tree in memory when writing it
> out, we may be able to output it in some sort of structured format.
> I would be hesitant to change how we write docs - this change took long
> enough to get in place, and the ability to add / remove bits to suit
> different projects is a good thing. Pages like [1] would be hard to do
> in a standard machine readable format, and I think they definitely make
> the docs better.
> - Graham
> 1 - https://developer.openstack.org/api-ref/compute/#servers-servers

Ok, I have done a quick (read: very rough and hacky) prototype of the
formatter here [1]

It uses the sphinx formatter plugin system, and reads from what we
already have in the api-ref/* folder.

It outputs [2] yaml that describes each endpoint, and the fields in the
request / response.

If there is interest, I can clean up the patch, and look at supporting

1 - https://review.openstack.org/#/c/528801/
2 - http://paste.openstack.org/show/629241/

- Graham

> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180104/54a6d621/attachment.sig>

More information about the OpenStack-dev mailing list