[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: QEMU HTML documentation now on qemu.org
From: |
Daniel P . Berrangé |
Subject: |
Re: QEMU HTML documentation now on qemu.org |
Date: |
Fri, 8 Nov 2019 09:45:25 +0000 |
User-agent: |
Mutt/1.12.1 (2019-06-15) |
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é <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.
>
> 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 :|