Re: QEMU HTML documentation now on qemu.org
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 > > > 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 signature.asc Description: PGP signature
Re: QEMU HTML documentation now on qemu.org
> You can now access the latest QEMU HTML documentation built from https://wiki.qemu.org/docs/qemu-doc.html 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.
Re: QEMU HTML documentation now on qemu.org
On Fri, Nov 08, 2019 at 09:41:30AM +0100, Stefan Hajnoczi wrote: > On Thu, Nov 07, 2019 at 04:01:42PM +, 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é > > > 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
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
On Thu, Nov 07, 2019 at 04:01:42PM +, 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é > > 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 signature.asc Description: PGP signature
Re: QEMU HTML documentation now on qemu.org
On Thu, 7 Nov 2019 at 09:29, Stefan Hajnoczi wrote: > > On Wed, Nov 6, 2019 at 5:21 PM 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! > > > > 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
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é > 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
On Thu, Nov 7, 2019 at 11:07 AM Daniel P. Berrangé 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
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
On Wed, Nov 6, 2019 at 5:21 PM 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! > > 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
QEMU HTML documentation now on qemu.org
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 signature.asc Description: PGP signature
