[Qemu-devel] GSoC project: API Documentation Generation links and comments

[Qemu-devel] GSoC project: API Documentation Generation links and comments

[Gabriel Barreto]

I've uploaded to my github repository¹ the work done so far. Using
Peter's patches as a starting point, we were able to generate
kernel-docs documentation for some of QEMU's APIs. After studying the
available options, we found a nice solution to publish the
documentation online and keep it updated, using Github Pages and
Travis CI. The idea is to use QEMU's Github mirror, updating the
documentation (located on a gh-pages branch) with every push done to
the master branch. I've implemented this and it's available at a
Github Page² on a gh-pages branch managed by travis jobs. The default
theme needs better structure, but a search in existing documentation
is possible as an out-of-the-box feature. My work is not done yet, as
I still need to rebase my commits to obtain a proper format for RFCs
and figure out a better alternative to deal with the massive number of
warnings that happen when generating the documentation. I'll keep
working on it and welcome any feedback from you. I'm available to
answer all questions you might have.


[1] https://github.com/gsb16/qemu
[2] https://gsb16.github.io/qemu/


Kind Regards,
Gabriel Barreto

Re: [Qemu-devel] GSoC project: API Documentation Generation links and comments

[John Snow]

On 8/26/19 2:51 PM, Gabriel Barreto wrote:
> I've uploaded to my github repository¹ the work done so far. Using
> Peter's patches as a starting point, we were able to generate
> kernel-docs documentation for some of QEMU's APIs. After studying the
> available options, we found a nice solution to publish the
> documentation online and keep it updated, using Github Pages and
> Travis CI. The idea is to use QEMU's Github mirror, updating the
> documentation (located on a gh-pages branch) with every push done to
> the master branch. I've implemented this and it's available at a
> Github Page² on a gh-pages branch managed by travis jobs. The default
> theme needs better structure, but a search in existing documentation
> is possible as an out-of-the-box feature. My work is not done yet, as
> I still need to rebase my commits to obtain a proper format for RFCs
> and figure out a better alternative to deal with the massive number of
> warnings that happen when generating the documentation. I'll keep
> working on it and welcome any feedback from you. I'm available to
> answer all questions you might have.
> 
> 
> [1] https://github.com/gsb16/qemu
> [2] https://gsb16.github.io/qemu/
> 
> 
> Kind Regards,
> Gabriel Barreto
> 

Ah, nice!


Some observations / questions:

- Having up-to-date documentation available on every push will be
convenient. I'm not sure if github pages will be the right home for
this, because I am not sure we are committed to maintaining a presence
on that page. ...I'd argue that it's better than not hosting our sphinx
documentation anywhere, ever, though.

- For theming, I'm a fan of the RTD theme, because I think it makes the
TOC tree stand out better and makes for nicer browsing than the default
alabaster theme. Maybe when there's a better over-arching TOC laid out
with better organization we could see which themes the list likes best.

- I imagine it's not too much work to get this to integrate with our
other existing manuals, too? (This looks like JUST kdoc generated
information, right?)

- The headers manual section is not organized into any logical
subsection or manual; it's useful to have for search, but probably isn't
very good reading as-is. We might want to filter these to be near the
features they're related to?

- https://gsb16.github.io/qemu/qapi/qjson.html and similar pages are
just simply empty. Either we want to populate them with stubs or just
omit empty pages, probably.

- https://gsb16.github.io/qemu/qom/cpu.html Do the build logs generate
errors like this in a visible way, or is this an invisible failure?




For now, what's your next steps? We need to get your code out of github
and onto the mailing list for review; do you have a todo list or any
issues you were hoping to tackle before you tried to send it out?

--js

Re: [Qemu-devel] GSoC project: API Documentation Generation links and comments

[Peter Maydell]

On Tue, 27 Aug 2019 at 21:52, John Snow <jsnow@redhat.com> wrote:
> - For theming, I'm a fan of the RTD theme, because I think it makes the
> TOC tree stand out better and makes for nicer browsing than the default
> alabaster theme. Maybe when there's a better over-arching TOC laid out
> with better organization we could see which themes the list likes best.

FWIW, for the in-tree doc generation I opted for Alabaster
(though I prefer RTD's look as well) because Alabaster doesn't
require shipping any fonts, whereas RTD does, and it seemed
easier to sidestep any questions about whether a font file in the
docs was mere aggregation or not. For "putting docs up on the
website" this doesn't apply so much, I think. Awkwardly, the
two themes aren't completely drop-in replacements, though:
I found that some of the tweaks needed for stuff like the
sidebar to come out the way I wanted were theme-specific.

thanks
-- PMM

Re: [Qemu-devel] GSoC project: API Documentation Generation links and comments

[John Snow]

On 8/27/19 4:56 PM, Peter Maydell wrote:
> On Tue, 27 Aug 2019 at 21:52, John Snow <jsnow@redhat.com> wrote:
>> - For theming, I'm a fan of the RTD theme, because I think it makes the
>> TOC tree stand out better and makes for nicer browsing than the default
>> alabaster theme. Maybe when there's a better over-arching TOC laid out
>> with better organization we could see which themes the list likes best.
> 
> FWIW, for the in-tree doc generation I opted for Alabaster
> (though I prefer RTD's look as well) because Alabaster doesn't
> require shipping any fonts, whereas RTD does, and it seemed
> easier to sidestep any questions about whether a font file in the
> docs was mere aggregation or not. For "putting docs up on the

What do you mean by "mere aggregation"?

> website" this doesn't apply so much, I think. Awkwardly, the
> two themes aren't completely drop-in replacements, though:
> I found that some of the tweaks needed for stuff like the
> sidebar to come out the way I wanted were theme-specific.
> 

That's... unfortunate. I've been playing around with RTD and Alabaster
for a hobby project, but hadn't noticed anything too different yet.

Of course, QEMU is gigantic and it is an edge-case magnet.

--js

Re: [Qemu-devel] GSoC project: API Documentation Generation links and comments

[Peter Maydell]

On Tue, 27 Aug 2019 at 22:01, John Snow <jsnow@redhat.com> wrote:
>
>
>
> On 8/27/19 4:56 PM, Peter Maydell wrote:
> > On Tue, 27 Aug 2019 at 21:52, John Snow <jsnow@redhat.com> wrote:
> >> - For theming, I'm a fan of the RTD theme, because I think it makes the
> >> TOC tree stand out better and makes for nicer browsing than the default
> >> alabaster theme. Maybe when there's a better over-arching TOC laid out
> >> with better organization we could see which themes the list likes best.
> >
> > FWIW, for the in-tree doc generation I opted for Alabaster
> > (though I prefer RTD's look as well) because Alabaster doesn't
> > require shipping any fonts, whereas RTD does, and it seemed
> > easier to sidestep any questions about whether a font file in the
> > docs was mere aggregation or not. For "putting docs up on the
>
> What do you mean by "mere aggregation"?

I mean what the GPL means by that term, ie the situation
where you can put a GPL-licensed thing and a non-GPL
licensed thing together without the non-GPL thing falling
under the terms of the GPL. (The canonical example is "Linux
distro CD which contains binaries for lots of different programs".)

thanks
-- PMM