* QEMU HTML documentation now on qemu.org @ 2019-11-06 16:19 Stefan Hajnoczi 2019-11-07 9:29 ` Stefan Hajnoczi 2019-11-07 10:06 ` Daniel P. Berrangé 0 siblings, 2 replies; 11+ messages in thread From: Stefan Hajnoczi @ 2019-11-06 16:19 UTC (permalink / raw) To: qemu-devel Cc: John Snow, Peter Maydell, Alex Bennée, Eduardo Habkost, Paolo Bonzini [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-06 16:19 QEMU HTML documentation now on qemu.org Stefan Hajnoczi @ 2019-11-07 9:29 ` Stefan Hajnoczi 2019-11-07 16:04 ` Peter Maydell 2019-11-07 10:06 ` Daniel P. Berrangé 1 sibling, 1 reply; 11+ messages in thread From: Stefan Hajnoczi @ 2019-11-07 9:29 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Peter Maydell, Eduardo Habkost, John Snow, qemu-devel, Markus Armbruster, Paolo Bonzini, Alex Bennée 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-07 9:29 ` Stefan Hajnoczi @ 2019-11-07 16:04 ` Peter Maydell 0 siblings, 0 replies; 11+ messages in thread From: Peter Maydell @ 2019-11-07 16:04 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Eduardo Habkost, John Snow, qemu-devel, Markus Armbruster, Stefan Hajnoczi, Paolo Bonzini, Alex Bennée 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-06 16:19 QEMU HTML documentation now on qemu.org Stefan Hajnoczi 2019-11-07 9:29 ` Stefan Hajnoczi @ 2019-11-07 10:06 ` Daniel P. Berrangé 2019-11-07 15:44 ` Stefan Hajnoczi 1 sibling, 1 reply; 11+ messages in thread From: Daniel P. Berrangé @ 2019-11-07 10:06 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Peter Maydell, Eduardo Habkost, John Snow, qemu-devel, Paolo Bonzini, Alex Bennée 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 :| ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-07 10:06 ` Daniel P. Berrangé @ 2019-11-07 15:44 ` Stefan Hajnoczi 2019-11-07 16:01 ` Daniel P. Berrangé 0 siblings, 1 reply; 11+ messages in thread From: Stefan Hajnoczi @ 2019-11-07 15:44 UTC (permalink / raw) To: Daniel P. Berrangé Cc: Peter Maydell, Eduardo Habkost, Alex Bennée, qemu-devel, Michael Roth, Stefan Hajnoczi, Paolo Bonzini, John Snow 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-07 15:44 ` Stefan Hajnoczi @ 2019-11-07 16:01 ` Daniel P. Berrangé 2019-11-08 8:41 ` Stefan Hajnoczi 0 siblings, 1 reply; 11+ messages in thread From: Daniel P. Berrangé @ 2019-11-07 16:01 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Peter Maydell, Eduardo Habkost, Alex Bennée, qemu-devel, Michael Roth, Stefan Hajnoczi, Paolo Bonzini, John Snow 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 :| ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-07 16:01 ` Daniel P. Berrangé @ 2019-11-08 8:41 ` Stefan Hajnoczi 2019-11-08 9:29 ` Paolo Bonzini 2019-11-08 9:45 ` Daniel P. Berrangé 0 siblings, 2 replies; 11+ messages in thread From: Stefan Hajnoczi @ 2019-11-08 8:41 UTC (permalink / raw) To: Daniel P. Berrangé Cc: Peter Maydell, Eduardo Habkost, Stefan Hajnoczi, qemu-devel, Michael Roth, Alex Bennée, Paolo Bonzini, John Snow [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-08 8:41 ` Stefan Hajnoczi @ 2019-11-08 9:29 ` Paolo Bonzini 2019-11-08 9:45 ` Daniel P. Berrangé 1 sibling, 0 replies; 11+ messages in thread From: Paolo Bonzini @ 2019-11-08 9:29 UTC (permalink / raw) To: Stefan Hajnoczi, Daniel P. Berrangé Cc: Peter Maydell, Eduardo Habkost, Stefan Hajnoczi, qemu-devel, Michael Roth, John Snow, Alex Bennée 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-08 8:41 ` Stefan Hajnoczi 2019-11-08 9:29 ` Paolo Bonzini @ 2019-11-08 9:45 ` Daniel P. Berrangé 1 sibling, 0 replies; 11+ messages in thread From: Daniel P. Berrangé @ 2019-11-08 9:45 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Peter Maydell, Eduardo Habkost, Stefan Hajnoczi, qemu-devel, Michael Roth, Alex Bennée, Paolo Bonzini, John Snow 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 :| ^ permalink raw reply [flat|nested] 11+ messages in thread
[parent not found: <mailman.2098.1573202511.13329.qemu-devel@nongnu.org>]
* Re: QEMU HTML documentation now on qemu.org [not found] <mailman.2098.1573202511.13329.qemu-devel@nongnu.org> @ 2019-11-15 14:05 ` G 3 2019-11-21 12:51 ` Stefan Hajnoczi 0 siblings, 1 reply; 11+ messages in thread From: G 3 @ 2019-11-15 14:05 UTC (permalink / raw) To: qemu-devel qemu-devel Cc: Peter Maydell, Daniel P. Berrange, Eduardo Habkost, Alex Bennée, Michael Roth, Stefan Hajnoczi, Paolo Bonzini, John Snow [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: QEMU HTML documentation now on qemu.org 2019-11-15 14:05 ` G 3 @ 2019-11-21 12:51 ` Stefan Hajnoczi 0 siblings, 0 replies; 11+ messages in thread From: Stefan Hajnoczi @ 2019-11-21 12:51 UTC (permalink / raw) To: G 3 Cc: Peter Maydell, Daniel P. Berrange, Eduardo Habkost, John Snow, Michael Roth, qemu-devel qemu-devel, Stefan Hajnoczi, Paolo Bonzini, Alex Bennée [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2019-11-21 12:51 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-11-06 16:19 QEMU HTML documentation now on qemu.org Stefan Hajnoczi
2019-11-07 9:29 ` Stefan Hajnoczi
2019-11-07 16:04 ` Peter Maydell
2019-11-07 10:06 ` Daniel P. Berrangé
2019-11-07 15:44 ` Stefan Hajnoczi
2019-11-07 16:01 ` Daniel P. Berrangé
2019-11-08 8:41 ` Stefan Hajnoczi
2019-11-08 9:29 ` Paolo Bonzini
2019-11-08 9:45 ` Daniel P. Berrangé
[not found] <mailman.2098.1573202511.13329.qemu-devel@nongnu.org>
2019-11-15 14:05 ` G 3
2019-11-21 12:51 ` Stefan Hajnoczi
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).