Re: QEMU HTML documentation now on qemu.org

[Daniel P . Berrangé]

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é <address@hidden> 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/address@hidden/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.

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 :|