Re: QEMU HTML documentation now on qemu.org

["Daniel P. Berrangé" <berrange@redhat.com>]

On Fri, Nov 08, 2019 at 09:41:30AM +0100, Stefan Hajnoczi wrote:
> On Thu, Nov 07, 2019 at 04:01:42PM +0000, Daniel P. Berrangé wrote:
> > On Thu, Nov 07, 2019 at 04:44:34PM +0100, Stefan Hajnoczi wrote:
> > > On Thu, Nov 7, 2019 at 11:07 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
> > > >
> > > > On Wed, Nov 06, 2019 at 05:19:28PM +0100, Stefan Hajnoczi wrote:
> > > > > Hi,
> > > > > You can now access the latest QEMU HTML documentation built from
> > > > > qemu.git/master nightly at:
> > > > >
> > > > >   https://wiki.qemu.org/docs/qemu-doc.html
> > > > >   https://wiki.qemu.org/docs/qemu-qmp-ref.html
> > > > >   https://wiki.qemu.org/docs/qemu-ga-ref.html
> > > > >   ...as well as interop/ and specs/
> > > > >
> > > > > Feel free to link to the documentation from the QEMU website and/or
> > > > > wiki!
> > > >
> > > > What's the reason for putting on wiki.qemu.org URL ? It feels like
> > > > having it under www.qemu.org would be a more natural home, especially
> > > > if we can then make it pick up the jekyll theme around the pages.
> > > >
> > > > Ideally we should publish the docs under versioned URL when we
> > > > make a release. eg  /docs/latest/....  for current GIT master
> > > > which I presume the above is tracking, and then a /docs/$VERSION/...
> > > > for each major release we cut.
> > > >
> > > > That way users can get an accurate view of features in the QEMU
> > > > they are actually using.
> > > 
> > > Versioned release docs should be generated during the release process.
> > > I have CCed Mike Roth.  That way the docs are available as soon as the
> > > release drops.  This container image only runs once a day and would
> > > leave a window when users cannot access the docs yet.
> > > 
> > > Moving from wiki.qemu.org should be possible.  How does the jekyll
> > > theme you mentioned work?
> > 
> > IIUC, when there's a push to the qemu-web.git repo, some git hook (?)
> > runs on the server which invokes jekyll to build the content, and
> > then publish it to the webroot.
> > 
> > To integrate these docs into that we need something along the lines
> > of:
> > 
> >   1. Generate the HTML files as you do now
> >   2. Copy them into the qemu-web.git in a /docs/ subdir
> >   3. Prepend a magic header to make jeykll process the file
> > 
> >      ---
> >      permalink: /docs/qemu-doc
> >      ---
> > 
> >   4. Trigger the jekyll builder to refresh the generated docs
> >   5. Publish the docs to the webroot
> > 
> > You can see what I did here  as an example where I simply committed
> > the generated docs to qemu-web.git:
> > 
> >   https://www.mail-archive.com/qemu-devel@nongnu.org/msg578110.html
> > 
> > If we're not storing the generated docs in git, then when
> > pushing to qemu-web.git we need to ensure we preserve the
> > extra /docs dir content in some manner.
> 
> For qemu.git/master the built docs might change every day.  Committing
> them to qemu-web.git seems like overkill.  I'll send a documentation.md
> patch for qemu-web.git instead that simply links to
> wiki.qemu.org/docs/.

Yeah, to be clear I wasn't suggesting committing them to qemu-web.git.
Really we just need to put the generated .html files into some scratch
directory on the web server where there qemu-web.git jekyll build can
automatically find them & process them in the same way it does for
content that is committed.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|