[ovirt-devel] Publicly available REST documentation

[Petr Horacek]

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.

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