[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: QEMU HTML documentation now on qemu.org
From: |
Stefan Hajnoczi |
Subject: |
Re: QEMU HTML documentation now on qemu.org |
Date: |
Fri, 8 Nov 2019 09:41:30 +0100 |
User-agent: |
Mutt/1.12.1 (2019-06-15) |
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/.
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
signature.asc
Description: PGP signature