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

[John Snow <jsnow@redhat.com>]

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