Re: QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi <stefanha@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3090 bytes --]

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/.

For release docs the process you described sounds good.  Peter Maydell
or Mike Roth may be interested in integrating it into the release
scripts.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]