[ovirt-devel] Publicly available REST documentation

Wed Jan 4 16:08:04 UTC 2017

Hello again, built master documentation is available on [1], latest
4.1 and 4.0 tags on [2] and [3] (these two were created manually,
automated build will be triggered by a next tag).

[1] http://ovirt.github.io/ovirt-engine-api-model/master/
[2] http://ovirt.github.io/ovirt-engine-api-model/4.1/
[3] http://ovirt.github.io/ovirt-engine-api-model/4.0/

2017-01-03 15:22 GMT+01:00 Juan Hernández <jhernand at redhat.com>:
> On 01/03/2017 03:20 PM, Petr Horacek wrote:
>> Hi, I've been hacking public API docs yesterday, and I think it will
>> work in GitHub-Travis combination. Now I am waiting if Gerrit-GitHub
>> mirroring will remove branch created directly on GitHub, if not, then
>> my approach would be following:
>>
>> Both 4.0 and 4.1 branches will have .travis.yml in them that will run
>> the build and then push generated pages to gh-pages branch (authorized
>> via GitHub deploy key). For now I have a working demo on my fork
>> (https://github.com/phoracek/ovirt-engine-api-model/blob/master/.travis.yml),
>> this one does not use deploy keys, but token instead.
>>
>> Hope I'm not breaking your work.
>>
>
> Excellent! Please go ahead.
>
>> 2017-01-03 14:49 GMT+01:00 Vojtech Szocs <vszocs at redhat.com>:
>>>
>>>
>>> ----- Original Message -----
>>>> From: "Rafael Martins" <rmartins at redhat.com>
>>>> To: "Vojtech Szocs" <vszocs at redhat.com>
>>>> Cc: "Juan Hernández" <jhernand at redhat.com>, "Michal Skrivanek" <mskrivan at redhat.com>, "devel" <devel at ovirt.org>
>>>> Sent: Tuesday, January 3, 2017 2:28:30 PM
>>>> Subject: Re: [ovirt-devel] Publicly available REST documentation
>>>>
>>>>
>>>>
>>>> ----- Original Message -----
>>>>> From: "Vojtech Szocs" <vszocs at redhat.com>
>>>>> To: "Rafael Martins" <rmartins at redhat.com>
>>>>> Cc: "Juan Hernández" <jhernand at redhat.com>, "Michal Skrivanek"
>>>>> <mskrivan at redhat.com>, "devel" <devel at ovirt.org>
>>>>> Sent: Tuesday, January 3, 2017 2:24:22 PM
>>>>> Subject: Re: [ovirt-devel] Publicly available REST documentation
>>>>>
>>>>>
>>>>>
>>>>> ----- Original Message -----
>>>>>> From: "Rafael Martins" <rmartins at redhat.com>
>>>>>> To: "Vojtech Szocs" <vszocs at redhat.com>
>>>>>> Cc: "Juan Hernández" <jhernand at redhat.com>, "Michal Skrivanek"
>>>>>> <mskrivan at redhat.com>, "devel" <devel at ovirt.org>
>>>>>> Sent: Tuesday, January 3, 2017 2:17:49 PM
>>>>>> Subject: Re: [ovirt-devel] Publicly available REST documentation
>>>>>>
>>>>>> ----- Original Message -----
>>>>>>> From: "Vojtech Szocs" <vszocs at redhat.com>
>>>>>>> To: "Juan Hernández" <jhernand at redhat.com>
>>>>>>> Cc: "Michal Skrivanek" <mskrivan at redhat.com>, "devel" <devel at ovirt.org>
>>>>>>> Sent: Tuesday, January 3, 2017 2:11:06 PM
>>>>>>> Subject: Re: [ovirt-devel] Publicly available REST documentation
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> ----- Original Message -----
>>>>>>>> From: "Juan Hernández" <jhernand at redhat.com>
>>>>>>>> To: "Jakub Niedermertl" <jniederm at redhat.com>
>>>>>>>> Cc: "devel" <devel at ovirt.org>, "Michal Skrivanek"
>>>>>>>> <mskrivan at redhat.com>
>>>>>>>> Sent: Monday, January 2, 2017 10:48:53 PM
>>>>>>>> Subject: Re: [ovirt-devel] Publicly available REST documentation
>>>>>>>>
>>>>>>>> On 01/02/2017 10:13 PM, Jakub Niedermertl wrote:
>>>>>>>>> Hi Juan,
>>>>>>>>>
>>>>>>>>> from time to time I'd like the REST doc to be available on some
>>>>>>>>> public
>>>>>>>>> site. It would allow us to
>>>>>>>>> * check the documentation without searching for running engine
>>>>>>>>> * be able to easily link documentations in irc/mails
>>>>>>>>> * link rest doc from ovirt.org site doc
>>>>>>>>> Recently I've also heard similar request from other guys (cc-ed).
>>>>>>>>> Would it be possible to for example publish generated doc of merged
>>>>>>>>> patches of ovirt-engine-api-model project? Maybe github project
>>>>>>>>> pages
>>>>>>>>> [1] of project mirror [2] could be used for hosting.
>>>>>>>>>
>>>>>>>>> Regards
>>>>>>>>> Jakub
>>>>>>>>>
>>>>>>>>> [1]
>>>>>>>>> https://help.github.com/articles/user-organization-and-project-pages/#project-pages
>>>>>>>>> [2] https://github.com/oVirt/ovirt-engine-api-model
>>>>>>>>>
>>>>>>>>
>>>>>>>> Yes, we can publish the documentation using gh-pages. I just created
>>>>>>>> and
>>>>>>>> populated the 'gh-branch' with some initial content, and requested
>>>>>>>> the
>>>>>>>> activation of the feature in Github. I will inform you when it is
>>>>>>>> ready.
>>>>>>>
>>>>>>> Alternatively, you could use readthedocs.org which supports webhooks:
>>>>>>> a push to GitHub (mirror) project [syncing Gerrit with GitHub] would
>>>>>>> regenerate the project's documentation available at
>>>>>>>
>>>>>>>   <your-project>.readthedocs.io
>>>>>>>
>>>>>>> which would allow to separate the GitHub project from its docs, given
>>>>>>> the source comes from Gerrit.
>>>>>>
>>>>>> ReadTheDocs relies on sphinx and/or mkdocs to rebuild the docs when
>>>>>> called
>>>>>> by
>>>>>> the webhook, and we use something else. We just need some hosting for
>>>>>> static
>>>>>> files, then github-pages is a better solution.
>>>>>
>>>>> Hm, and what about pushing to https://github.com/oVirt/ovirt-site directly,
>>>>> instead of pushing to GitHub (mirror) project pages?
>>>>
>>>> there's no real need to mess with the ovirt-site repo. we can have a
>>>> separated repo, that can be freely updated by a jenkins job, for example,
>>>> and include it on ovirt-site using a sub-repository, like it is done for
>>>> data/events today. The good thing of this approach is that we can have
>>>> "unstable" docs in the separated repo, updated by jenkins, and just checkout
>>>> stable versions on the ovirt-site subrepo.
>>>
>>> I like the idea of <project-x-docs> as sub-repo of <ovirt-site> :)
>>>
>>> Thanks for your response, it makes sense.
>>>
>>>>
>>>> Rafael
>>>>
>>>>>>
>>>>>> Thanks.
>>>>>> Rafael
>>>>>>
>>>>>>>> _______________________________________________
>>>>>>>> Devel mailing list
>>>>>>>> Devel at ovirt.org
>>>>>>>> http://lists.ovirt.org/mailman/listinfo/devel
>>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Devel mailing list
>>>>>>> Devel at ovirt.org
>>>>>>> http://lists.ovirt.org/mailman/listinfo/devel
>>>>>>
>>>>>
>>>>
>>> _______________________________________________
>>> Devel mailing list
>>> Devel at ovirt.org
>>> http://lists.ovirt.org/mailman/listinfo/devel
>