QEMU HTML documentation now on qemu.org

QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi]

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

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!

The container image that builds the docs is here:

  https://github.com/stefanha/qemu-docs

It is hosted on QEMU's Rackspace cloud account.

Stefan

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

Re: QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi]

On Wed, Nov 6, 2019 at 5:21 PM Stefan Hajnoczi <stefanha@redhat.com> 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!
>
> The container image that builds the docs is here:
>
>   https://github.com/stefanha/qemu-docs
>
> It is hosted on QEMU's Rackspace cloud account.

I forgot to add Markus.

I hope this helps the QEMU documentation effort.  I currently do not
have plans to work on this further.  You are welcome to send pull
requests to the qemu-docs container image repo or just ask me and I'll
make changes.

Stefan

Re: QEMU HTML documentation now on qemu.org

[Daniel P. Berrangé]

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.

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

Re: QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi]

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?

Stefan

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

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

Re: QEMU HTML documentation now on qemu.org

[Peter Maydell]

On Thu, 7 Nov 2019 at 09:29, Stefan Hajnoczi <stefanha@gmail.com> wrote:
>
> On Wed, Nov 6, 2019 at 5:21 PM Stefan Hajnoczi <stefanha@redhat.com> 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!
> >
> > The container image that builds the docs is here:
> >
> >   https://github.com/stefanha/qemu-docs
> >
> > It is hosted on QEMU's Rackspace cloud account.
>
> I forgot to add Markus.
>
> I hope this helps the QEMU documentation effort.  I currently do not
> have plans to work on this further.  You are welcome to send pull
> requests to the qemu-docs container image repo or just ask me and I'll
> make changes.

Yep, it's definitely helpful.

One simple thing we could perhaps add is a hand-written
"top level" page which just has links to the various
documentation URLs you list above. (Possibly this should
be done in-tree so the in-tree docs also have a top
level landing page.)

thanks
-- PMM

Re: QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi]

[-- 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 --]

Re: QEMU HTML documentation now on qemu.org

[Paolo Bonzini]

On 08/11/19 09:41, Stefan Hajnoczi wrote:
>> 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/.

I think this is a good first step.  Perhaps in the long term we want to
have docs.qemu.org/latest/ link to the latest release,
docs.qemu.org/unstable/ rebuilt from master, etc.

Paolo

Re: QEMU HTML documentation now on qemu.org

[Daniel P. Berrangé]

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

Re: QEMU HTML documentation now on qemu.org

[Stefan Hajnoczi]

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

On Fri, Nov 15, 2019 at 09:05:32AM -0500, G 3 wrote:
> > You can now access the latest QEMU HTML documentation built from
> 
> https://wiki.qemu.org/docs/qemu-doc.html
> <snip>
> 
> This is a welcome start. Could we add version support to the URL?
> 
> What I mean is add the version number to the path of the URL.
> Like this:
> https://wiki.qemu.org/docs/4.2/qemu-doc.html
> 
> This way users of older versions of QEMU can still access documentation
> relevant to his or her version.

The current setup only builds qemu.git/master.  The final URL is now:

  https://www.qemu.org/docs/master/qemu-doc.html

Mike Roth could add something to the release process that publishes
versioned HTML documentation.

There probably won't be much activity around this until after QEMU 4.2
has been released.  My patches haven't been reviewed/merged because of
the code freeze.

Stefan

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

Re: QEMU HTML documentation now on qemu.org

[G 3]

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

> You can now access the latest QEMU HTML documentation built from

https://wiki.qemu.org/docs/qemu-doc.html
<snip>

This is a welcome start. Could we add version support to the URL?

What I mean is add the version number to the path of the URL.
Like this:
https://wiki.qemu.org/docs/4.2/qemu-doc.html

This way users of older versions of QEMU can still access documentation
relevant to his or her version.

Thank you.

[-- Attachment #2: Type: text/html, Size: 812 bytes --]