| Message ID | 20181203164105.29858-1-berrange@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [qemu-web] Import historical documentation | expand |
Hi On Mon, Dec 3, 2018 at 9:23 PM Daniel P. Berrangé <berrange@redhat.com> wrote: > > The files included are taken from formal builds of previous versions > of QEMU, going back to 2.0.0 > > - qemu-doc.html > - qemu-qmp-ref.html > - qemu-ga-ref.html > > To import them all content outside of <body></body> is stripped and > replaced by a trivial jekyll header. This causes the rendered docs > to get consistent styling and navbar heading. > > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Nice! Except the minor link issue of 2.11, Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> > --- > > This patch shows what it would be like if we just copied the > pre-rendered QEMU docs into qemu-web for each major release.... > > ...it would be large. 2.0.0 was only 300 KB in size, but latest > 3.0.0 release has 1.3 MB of docs. So we'd be adding about 4 MB > of docs to qemu-web each year if we committed them. > > This feels undesirable as a strategy. Isn't git storage/packing smart enough? $ du -sch reference/*/*.html 8.9M total $ du -sh .git 1.5M .git It's doing a good job. > > I trimmed this mail to cut out the .html files to avoid spamming > the list. If you want to see the full commit it is here: > > https://github.com/berrange/qemu-web/commit/c5f6d0f8664d7edd016f469f0709caec8360f783 > > At least in terms of the end result for users, I think it is > positive. > > Other ideas > > 1. Upload built docs to a lookaside directory on the download > site when making a release, then have a jekyll plugin to > pull them in. Extra work for the person making releases > principally. > > 2. Have a jekyll plugin that uses docker env to build each > release docs from pristine tarballs. Would need caching > to avoid burning CPU cycles in each web update. Reliably > building older QEMU versions gets increasingly troublesome > > assets/css/style.css | 14 + > documentation.md | 78 +- > reference/2.0.0/qemu-doc.html | 7323 +++++++++ > reference/2.1.0/qemu-doc.html | 7567 ++++++++++ > reference/2.10.0/qemu-doc.html | 10026 +++++++++++++ > reference/2.10.0/qemu-ga-ref.html | 1947 +++ > reference/2.10.0/qemu-qmp-ref.html | 18766 +++++++++++++++++++++++ > reference/2.11.0/qemu-doc.html | 10128 +++++++++++++ > reference/2.11.0/qemu-ga-ref.html | 1993 +++ > reference/2.11.0/qemu-qmp-ref.html | 19171 ++++++++++++++++++++++++ > reference/2.12.0/qemu-doc.html | 10555 +++++++++++++ > reference/2.12.0/qemu-ga-ref.html | 1931 +++ > reference/2.12.0/qemu-qmp-ref.html | 20616 +++++++++++++++++++++++++ > reference/2.2.0/qemu-doc.html | 7622 ++++++++++ > reference/2.3.0/qemu-doc.html | 7692 ++++++++++ > reference/2.4.0/qemu-doc.html | 7812 ++++++++++ > reference/2.5.0/qemu-doc.html | 8300 +++++++++++ > reference/2.6.0/qemu-doc.html | 8647 +++++++++++ > reference/2.7.0/qemu-doc.html | 8771 +++++++++++ > reference/2.8.0/qemu-doc.html | 9097 ++++++++++++ > reference/2.9.0/qemu-doc.html | 9209 ++++++++++++ > reference/2.9.0/qemu-ga-ref.html | 1693 +++ > reference/2.9.0/qemu-qmp-ref.html | 18082 ++++++++++++++++++++++ > reference/3.0.0/qemu-doc.html | 10810 ++++++++++++++ > reference/3.0.0/qemu-ga-ref.html | 1939 +++ > reference/3.0.0/qemu-qmp-ref.html | 21458 +++++++++++++++++++++++++++ > 26 files changed, 231246 insertions(+), 1 deletion(-) > create mode 100644 reference/2.0.0/qemu-doc.html > create mode 100644 reference/2.1.0/qemu-doc.html > create mode 100644 reference/2.10.0/qemu-doc.html > create mode 100644 reference/2.10.0/qemu-ga-ref.html > create mode 100644 reference/2.10.0/qemu-qmp-ref.html > create mode 100644 reference/2.11.0/qemu-doc.html > create mode 100644 reference/2.11.0/qemu-ga-ref.html > create mode 100644 reference/2.11.0/qemu-qmp-ref.html > create mode 100644 reference/2.12.0/qemu-doc.html > create mode 100644 reference/2.12.0/qemu-ga-ref.html > create mode 100644 reference/2.12.0/qemu-qmp-ref.html > create mode 100644 reference/2.2.0/qemu-doc.html > create mode 100644 reference/2.3.0/qemu-doc.html > create mode 100644 reference/2.4.0/qemu-doc.html > create mode 100644 reference/2.5.0/qemu-doc.html > create mode 100644 reference/2.6.0/qemu-doc.html > create mode 100644 reference/2.7.0/qemu-doc.html > create mode 100644 reference/2.8.0/qemu-doc.html > create mode 100644 reference/2.9.0/qemu-doc.html > create mode 100644 reference/2.9.0/qemu-ga-ref.html > create mode 100644 reference/2.9.0/qemu-qmp-ref.html > create mode 100644 reference/3.0.0/qemu-doc.html > create mode 100644 reference/3.0.0/qemu-ga-ref.html > create mode 100644 reference/3.0.0/qemu-qmp-ref.html > diff --git a/assets/css/style.css b/assets/css/style.css > index b828887..b1d7339 100644 > --- a/assets/css/style.css > +++ b/assets/css/style.css > @@ -590,3 +590,17 @@ > { > margin-top: 1.5em; > } > + > + #refdoc { > + border-spacing: 4px; > + } > + #refdoc td { > + background: rgb(240,240,240); > + padding: 6px; > + margin: 6px; > + } > + #refdoc th { > + background: rgb(220,220,220); > + padding: 6px; > + text-align: right; > + } > diff --git a/documentation.md b/documentation.md > index f4ef9f4..571259d 100644 > --- a/documentation.md > +++ b/documentation.md > @@ -3,7 +3,11 @@ title: QEMU documentation > permalink: /documentation/ > --- > > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil. > +## Reference guides > + > +The table below provides copies of the formal documentation associated > +with each release of QEMU. > + > More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a> > directory of the QEMU git tree. > > @@ -11,3 +15,75 @@ The [QEMU wiki](https://wiki.qemu.org) contains more > [user documentation](https://wiki.qemu.org/Category:User_documentation) and > [developer documentation](https://wiki.qemu.org/Category:Developer_documentation) > that has not been integrated into the QEMU git tree. > + > +<table id="refdoc"> > +<tbody> > +<tr> > +<th>3.0.0</th> > +<td><a href="/reference/3.0.0/qemu-doc.html">User guide</a></td> > +<td><a href="/reference/3.0.0/qemu-qmp-ref.html">QMP ref</a></td> > +<td><a href="/reference/3.0.0/qemu-ga-ref.html">GA ref</a></td> > +</tr> > +<tr> > +<th>2.12.0</th> > +<td><a href="/reference/2.12.0/qemu-doc.html">User guide</a></td> > +<td><a href="/reference/2.12.0/qemu-qmp-ref.html">QMP ref</a></td> > +<td><a href="/reference/2.12.0/qemu-ga-ref.html">GA ref</a></td> > +</tr> > +<tr> > +<th>2.11.0</th> > +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> > +<td><a href="/reference/2.11.0/qemu-qmp-ref.html">QMP ref</a></td> > +<td><a href="/reference/2.11.0/qemu-ga-ref.html">GA ref</a></td> > +</tr> > +<tr> > +<th>2.10.0</th> > +<td><a href="/reference/2.10.0/qemu-doc.html">User guide</a></td> > +<td><a href="/reference/2.10.0/qemu-qmp-ref.html">QMP ref</a></td> > +<td><a href="/reference/2.10.0/qemu-ga-ref.html">GA ref</a></td> > +</tr> > +<tr> > +<th>2.9.0</th> > +<td><a href="/reference/2.9.0/qemu-doc.html">User guide</a></td> > +<td><a href="/reference/2.9.0/qemu-qmp-ref.html">QMP ref</a></td> > +<td><a href="/reference/2.9.0/qemu-ga-ref.html">GA ref</a></td> > +</tr> > +<tr> > +<th>2.8.0</th> > +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> 2.11 ? > +</tr> > +<tr> > +<th>2.7.0</th> > +<td><a href="/reference/2.7.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.6.0</th> > +<td><a href="/reference/2.6.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.5.0</th> > +<td><a href="/reference/2.5.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.4.0</th> > +<td><a href="/reference/2.4.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.3.0</th> > +<td><a href="/reference/2.3.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.2.0</th> > +<td><a href="/reference/2.2.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.1.0</th> > +<td><a href="/reference/2.1.0/qemu-doc.html">User guide</a></td> > +</tr> > +<tr> > +<th>2.0.0</th> > +<td><a href="/reference/2.0.0/qemu-doc.html">User guide</a></td> > +</tr> > +</tbody> > +</table> > + > diff --git a/reference/3.0.0/qemu-doc.html b/reference/3.0.0/qemu-doc.html > new file mode 100644 > index 0000000..e7abe8f > --- /dev/null > +++ b/reference/3.0.0/qemu-doc.html > @@ -0,0 +1,18 @@ > +--- > +permalink: reference/3.0.0/qemu-doc.html > +--- > +<h1 class="settitle" align="center">QEMU version 3.0.0 User Documentation</h1> > + > + > + > + > + > +<a name="Top"></a> > +<a name="SEC_Top"></a> > + > + > +<a name="SEC_Contents"></a> > +<h2 class="contents-heading">Table of Contents</h2> > + > +<div class="contents"> > + > > [...snip...] >
On Mon, Dec 03, 2018 at 11:14:48PM +0400, Marc-André Lureau wrote: > Hi > > On Mon, Dec 3, 2018 at 9:23 PM Daniel P. Berrangé <berrange@redhat.com> wrote: > > > > The files included are taken from formal builds of previous versions > > of QEMU, going back to 2.0.0 > > > > - qemu-doc.html > > - qemu-qmp-ref.html > > - qemu-ga-ref.html > > > > To import them all content outside of <body></body> is stripped and > > replaced by a trivial jekyll header. This causes the rendered docs > > to get consistent styling and navbar heading. > > > > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> > > Nice! Except the minor link issue of 2.11, > > Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> > > > --- > > > > This patch shows what it would be like if we just copied the > > pre-rendered QEMU docs into qemu-web for each major release.... > > > > ...it would be large. 2.0.0 was only 300 KB in size, but latest > > 3.0.0 release has 1.3 MB of docs. So we'd be adding about 4 MB > > of docs to qemu-web each year if we committed them. > > > > This feels undesirable as a strategy. > > Isn't git storage/packing smart enough? > > $ du -sch reference/*/*.html > 8.9M total > $ du -sh .git > 1.5M .git > > It's doing a good job. Oh yes, I didn't think to check that - was just looking at general repo / patchfile size. That is not unreasonably large for .git If Paolo/Thomas think this is acceptable, the full patch is at my github below... > > > > > I trimmed this mail to cut out the .html files to avoid spamming > > the list. If you want to see the full commit it is here: > > > > https://github.com/berrange/qemu-web/commit/c5f6d0f8664d7edd016f469f0709caec8360f783 > > > > At least in terms of the end result for users, I think it is > > positive. > > > > Other ideas > > > > 1. Upload built docs to a lookaside directory on the download > > site when making a release, then have a jekyll plugin to > > pull them in. Extra work for the person making releases > > principally. > > > > 2. Have a jekyll plugin that uses docker env to build each > > release docs from pristine tarballs. Would need caching > > to avoid burning CPU cycles in each web update. Reliably > > building older QEMU versions gets increasingly troublesome > > > > assets/css/style.css | 14 + > > documentation.md | 78 +- > > reference/2.0.0/qemu-doc.html | 7323 +++++++++ > > reference/2.1.0/qemu-doc.html | 7567 ++++++++++ > > reference/2.10.0/qemu-doc.html | 10026 +++++++++++++ > > reference/2.10.0/qemu-ga-ref.html | 1947 +++ > > reference/2.10.0/qemu-qmp-ref.html | 18766 +++++++++++++++++++++++ > > reference/2.11.0/qemu-doc.html | 10128 +++++++++++++ > > reference/2.11.0/qemu-ga-ref.html | 1993 +++ > > reference/2.11.0/qemu-qmp-ref.html | 19171 ++++++++++++++++++++++++ > > reference/2.12.0/qemu-doc.html | 10555 +++++++++++++ > > reference/2.12.0/qemu-ga-ref.html | 1931 +++ > > reference/2.12.0/qemu-qmp-ref.html | 20616 +++++++++++++++++++++++++ > > reference/2.2.0/qemu-doc.html | 7622 ++++++++++ > > reference/2.3.0/qemu-doc.html | 7692 ++++++++++ > > reference/2.4.0/qemu-doc.html | 7812 ++++++++++ > > reference/2.5.0/qemu-doc.html | 8300 +++++++++++ > > reference/2.6.0/qemu-doc.html | 8647 +++++++++++ > > reference/2.7.0/qemu-doc.html | 8771 +++++++++++ > > reference/2.8.0/qemu-doc.html | 9097 ++++++++++++ > > reference/2.9.0/qemu-doc.html | 9209 ++++++++++++ > > reference/2.9.0/qemu-ga-ref.html | 1693 +++ > > reference/2.9.0/qemu-qmp-ref.html | 18082 ++++++++++++++++++++++ > > reference/3.0.0/qemu-doc.html | 10810 ++++++++++++++ > > reference/3.0.0/qemu-ga-ref.html | 1939 +++ > > reference/3.0.0/qemu-qmp-ref.html | 21458 +++++++++++++++++++++++++++ > > 26 files changed, 231246 insertions(+), 1 deletion(-) > > create mode 100644 reference/2.0.0/qemu-doc.html > > create mode 100644 reference/2.1.0/qemu-doc.html > > create mode 100644 reference/2.10.0/qemu-doc.html > > create mode 100644 reference/2.10.0/qemu-ga-ref.html > > create mode 100644 reference/2.10.0/qemu-qmp-ref.html > > create mode 100644 reference/2.11.0/qemu-doc.html > > create mode 100644 reference/2.11.0/qemu-ga-ref.html > > create mode 100644 reference/2.11.0/qemu-qmp-ref.html > > create mode 100644 reference/2.12.0/qemu-doc.html > > create mode 100644 reference/2.12.0/qemu-ga-ref.html > > create mode 100644 reference/2.12.0/qemu-qmp-ref.html > > create mode 100644 reference/2.2.0/qemu-doc.html > > create mode 100644 reference/2.3.0/qemu-doc.html > > create mode 100644 reference/2.4.0/qemu-doc.html > > create mode 100644 reference/2.5.0/qemu-doc.html > > create mode 100644 reference/2.6.0/qemu-doc.html > > create mode 100644 reference/2.7.0/qemu-doc.html > > create mode 100644 reference/2.8.0/qemu-doc.html > > create mode 100644 reference/2.9.0/qemu-doc.html > > create mode 100644 reference/2.9.0/qemu-ga-ref.html > > create mode 100644 reference/2.9.0/qemu-qmp-ref.html > > create mode 100644 reference/3.0.0/qemu-doc.html > > create mode 100644 reference/3.0.0/qemu-ga-ref.html > > create mode 100644 reference/3.0.0/qemu-qmp-ref.html > > diff --git a/assets/css/style.css b/assets/css/style.css > > index b828887..b1d7339 100644 > > --- a/assets/css/style.css > > +++ b/assets/css/style.css > > @@ -590,3 +590,17 @@ > > { > > margin-top: 1.5em; > > } > > + > > + #refdoc { > > + border-spacing: 4px; > > + } > > + #refdoc td { > > + background: rgb(240,240,240); > > + padding: 6px; > > + margin: 6px; > > + } > > + #refdoc th { > > + background: rgb(220,220,220); > > + padding: 6px; > > + text-align: right; > > + } > > diff --git a/documentation.md b/documentation.md > > index f4ef9f4..571259d 100644 > > --- a/documentation.md > > +++ b/documentation.md > > @@ -3,7 +3,11 @@ title: QEMU documentation > > permalink: /documentation/ > > --- > > > > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil. > > +## Reference guides > > + > > +The table below provides copies of the formal documentation associated > > +with each release of QEMU. > > + > > More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a> > > directory of the QEMU git tree. > > > > @@ -11,3 +15,75 @@ The [QEMU wiki](https://wiki.qemu.org) contains more > > [user documentation](https://wiki.qemu.org/Category:User_documentation) and > > [developer documentation](https://wiki.qemu.org/Category:Developer_documentation) > > that has not been integrated into the QEMU git tree. > > + > > +<table id="refdoc"> > > +<tbody> > > +<tr> > > +<th>3.0.0</th> > > +<td><a href="/reference/3.0.0/qemu-doc.html">User guide</a></td> > > +<td><a href="/reference/3.0.0/qemu-qmp-ref.html">QMP ref</a></td> > > +<td><a href="/reference/3.0.0/qemu-ga-ref.html">GA ref</a></td> > > +</tr> > > +<tr> > > +<th>2.12.0</th> > > +<td><a href="/reference/2.12.0/qemu-doc.html">User guide</a></td> > > +<td><a href="/reference/2.12.0/qemu-qmp-ref.html">QMP ref</a></td> > > +<td><a href="/reference/2.12.0/qemu-ga-ref.html">GA ref</a></td> > > +</tr> > > +<tr> > > +<th>2.11.0</th> > > +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> > > +<td><a href="/reference/2.11.0/qemu-qmp-ref.html">QMP ref</a></td> > > +<td><a href="/reference/2.11.0/qemu-ga-ref.html">GA ref</a></td> > > +</tr> > > +<tr> > > +<th>2.10.0</th> > > +<td><a href="/reference/2.10.0/qemu-doc.html">User guide</a></td> > > +<td><a href="/reference/2.10.0/qemu-qmp-ref.html">QMP ref</a></td> > > +<td><a href="/reference/2.10.0/qemu-ga-ref.html">GA ref</a></td> > > +</tr> > > +<tr> > > +<th>2.9.0</th> > > +<td><a href="/reference/2.9.0/qemu-doc.html">User guide</a></td> > > +<td><a href="/reference/2.9.0/qemu-qmp-ref.html">QMP ref</a></td> > > +<td><a href="/reference/2.9.0/qemu-ga-ref.html">GA ref</a></td> > > +</tr> > > +<tr> > > +<th>2.8.0</th> > > +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> > > 2.11 ? Opps, I pushed the fix for that to github. I won't resend this patch mail for such an obvious change. Regards, Daniel
On 2018-12-03 17:41, Daniel P. Berrangé wrote: > The files included are taken from formal builds of previous versions > of QEMU, going back to 2.0.0 > > - qemu-doc.html > - qemu-qmp-ref.html > - qemu-ga-ref.html > > To import them all content outside of <body></body> is stripped and > replaced by a trivial jekyll header. This causes the rendered docs > to get consistent styling and navbar heading. > > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> > --- > > This patch shows what it would be like if we just copied the > pre-rendered QEMU docs into qemu-web for each major release.... > > ...it would be large. 2.0.0 was only 300 KB in size, but latest > 3.0.0 release has 1.3 MB of docs. So we'd be adding about 4 MB > of docs to qemu-web each year if we committed them. > > This feels undesirable as a strategy. I also dislike the idea to store data in the git repo that is generated automatically from other sources (qemu-doc.texi and friends in this case). > At least in terms of the end result for users, I think it is > positive. Agreed, for the users it might be helpful to have access to all different versions of the documenation. > Other ideas > > 1. Upload built docs to a lookaside directory on the download > site when making a release, then have a jekyll plugin to > pull them in. Extra work for the person making releases > principally. > > 2. Have a jekyll plugin that uses docker env to build each > release docs from pristine tarballs. Would need caching > to avoid burning CPU cycles in each web update. Reliably > building older QEMU versions gets increasingly troublesome We'd also need to discuss how new docs get added after a release anyway... automatically? Manually? In the latter case, who does that job? I think it would be best if we find a way to automate this process, e.g. when a new release is tagged, a script generates the docs and puts them somewhere on the web server, into the right new folder based on the name of the tag. However, I don't know the qemu server well enough to know whether that's possible or not ... maybe Jeff or Paolo can comment on this... Thomas
On 04/12/18 11:56, Thomas Huth wrote: > I think it would be best if we find a way to automate this process, e.g. > when a new release is tagged, a script generates the docs and puts them > somewhere on the web server, into the right new folder based on the name > of the tag. However, I don't know the qemu server well enough to know > whether that's possible or not ... maybe Jeff or Paolo can comment on > this... There are two possibilities: putting the docs on download.qemu.org and going for Marc-André's styling solution, or using a dash of sed to remove the <head> and use Jekyll to generate the page. Either way, there isn't much to do on the webserver side, so a better person to ask would be Mike Roth as he's the Guy Who Does The Releases. For either solution he'd have to build the documentation and scp it (if we go for download.qemu.org) or commit it to qemu-web.git (if we go for Jekyll). I guess he has scripts already to automate part of the release process, but I have no idea if the website update is automated already. Paolo
On Thu, Dec 06, 2018 at 09:01:46PM +0100, Paolo Bonzini wrote: > On 04/12/18 11:56, Thomas Huth wrote: > > I think it would be best if we find a way to automate this process, e.g. > > when a new release is tagged, a script generates the docs and puts them > > somewhere on the web server, into the right new folder based on the name > > of the tag. However, I don't know the qemu server well enough to know > > whether that's possible or not ... maybe Jeff or Paolo can comment on > > this... > > There are two possibilities: putting the docs on download.qemu.org and > going for Marc-André's styling solution, or using a dash of sed to > remove the <head> and use Jekyll to generate the page. I would really like the docs to be properly integrated into the web site including navbar / footers, not just using a similar-ish styling. > Either way, there isn't much to do on the webserver side, so a better > person to ask would be Mike Roth as he's the Guy Who Does The Releases. > For either solution he'd have to build the documentation and scp it (if > we go for download.qemu.org) or commit it to qemu-web.git (if we go for > Jekyll). I guess he has scripts already to automate part of the release > process, but I have no idea if the website update is automated already. A third option is to scp the docs to download.qemu.org (perhaps in a hidden dir), and then have a jekyll plugin that pulls that in & applies the template. Regards, Daniel
Quoting Daniel P. Berrangé (2018-12-07 03:44:45) > On Thu, Dec 06, 2018 at 09:01:46PM +0100, Paolo Bonzini wrote: > > On 04/12/18 11:56, Thomas Huth wrote: > > > I think it would be best if we find a way to automate this process, e.g. > > > when a new release is tagged, a script generates the docs and puts them > > > somewhere on the web server, into the right new folder based on the name > > > of the tag. However, I don't know the qemu server well enough to know > > > whether that's possible or not ... maybe Jeff or Paolo can comment on > > > this... > > > > There are two possibilities: putting the docs on download.qemu.org and > > going for Marc-André's styling solution, or using a dash of sed to > > remove the <head> and use Jekyll to generate the page. > > I would really like the docs to be properly integrated into the web > site including navbar / footers, not just using a similar-ish styling. > > > Either way, there isn't much to do on the webserver side, so a better > > person to ask would be Mike Roth as he's the Guy Who Does The Releases. > > For either solution he'd have to build the documentation and scp it (if > > we go for download.qemu.org) or commit it to qemu-web.git (if we go for > > Jekyll). I guess he has scripts already to automate part of the release > > process, but I have no idea if the website update is automated already. > > A third option is to scp the docs to download.qemu.org (perhaps in a hidden > dir), and then have a jekyll plugin that pulls that in & applies the > template. I have scripts to generate/build/test tarballs, but do the uploads manually and then manually do the qemu-web.git commit. So whether it's an extra upload or and extra commit/commit step works just as well on my end. Uploading the docs alongs with the tarballs at the appropriate locations and having jekyll do any additional processing as part of the _data/releases.yml update/commit would probably be ideal for me, but any of these approaches should work fine for me. Hidden directory makes sense if we don't plan to use them directly so we can easily delete them afterward to save space. > > 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 :| >
diff --git a/assets/css/style.css b/assets/css/style.css index b828887..b1d7339 100644 --- a/assets/css/style.css +++ b/assets/css/style.css @@ -590,3 +590,17 @@ { margin-top: 1.5em; } + + #refdoc { + border-spacing: 4px; + } + #refdoc td { + background: rgb(240,240,240); + padding: 6px; + margin: 6px; + } + #refdoc th { + background: rgb(220,220,220); + padding: 6px; + text-align: right; + } diff --git a/documentation.md b/documentation.md index f4ef9f4..571259d 100644 --- a/documentation.md +++ b/documentation.md @@ -3,7 +3,11 @@ title: QEMU documentation permalink: /documentation/ --- -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil. +## Reference guides + +The table below provides copies of the formal documentation associated +with each release of QEMU. + More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a> directory of the QEMU git tree. @@ -11,3 +15,75 @@ The [QEMU wiki](https://wiki.qemu.org) contains more [user documentation](https://wiki.qemu.org/Category:User_documentation) and [developer documentation](https://wiki.qemu.org/Category:Developer_documentation) that has not been integrated into the QEMU git tree. + +<table id="refdoc"> +<tbody> +<tr> +<th>3.0.0</th> +<td><a href="/reference/3.0.0/qemu-doc.html">User guide</a></td> +<td><a href="/reference/3.0.0/qemu-qmp-ref.html">QMP ref</a></td> +<td><a href="/reference/3.0.0/qemu-ga-ref.html">GA ref</a></td> +</tr> +<tr> +<th>2.12.0</th> +<td><a href="/reference/2.12.0/qemu-doc.html">User guide</a></td> +<td><a href="/reference/2.12.0/qemu-qmp-ref.html">QMP ref</a></td> +<td><a href="/reference/2.12.0/qemu-ga-ref.html">GA ref</a></td> +</tr> +<tr> +<th>2.11.0</th> +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> +<td><a href="/reference/2.11.0/qemu-qmp-ref.html">QMP ref</a></td> +<td><a href="/reference/2.11.0/qemu-ga-ref.html">GA ref</a></td> +</tr> +<tr> +<th>2.10.0</th> +<td><a href="/reference/2.10.0/qemu-doc.html">User guide</a></td> +<td><a href="/reference/2.10.0/qemu-qmp-ref.html">QMP ref</a></td> +<td><a href="/reference/2.10.0/qemu-ga-ref.html">GA ref</a></td> +</tr> +<tr> +<th>2.9.0</th> +<td><a href="/reference/2.9.0/qemu-doc.html">User guide</a></td> +<td><a href="/reference/2.9.0/qemu-qmp-ref.html">QMP ref</a></td> +<td><a href="/reference/2.9.0/qemu-ga-ref.html">GA ref</a></td> +</tr> +<tr> +<th>2.8.0</th> +<td><a href="/reference/2.11.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.7.0</th> +<td><a href="/reference/2.7.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.6.0</th> +<td><a href="/reference/2.6.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.5.0</th> +<td><a href="/reference/2.5.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.4.0</th> +<td><a href="/reference/2.4.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.3.0</th> +<td><a href="/reference/2.3.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.2.0</th> +<td><a href="/reference/2.2.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.1.0</th> +<td><a href="/reference/2.1.0/qemu-doc.html">User guide</a></td> +</tr> +<tr> +<th>2.0.0</th> +<td><a href="/reference/2.0.0/qemu-doc.html">User guide</a></td> +</tr> +</tbody> +</table> + diff --git a/reference/3.0.0/qemu-doc.html b/reference/3.0.0/qemu-doc.html new file mode 100644 index 0000000..e7abe8f --- /dev/null +++ b/reference/3.0.0/qemu-doc.html @@ -0,0 +1,18 @@ +--- +permalink: reference/3.0.0/qemu-doc.html +--- +<h1 class="settitle" align="center">QEMU version 3.0.0 User Documentation</h1> + + + + + +<a name="Top"></a> +<a name="SEC_Top"></a> + + +<a name="SEC_Contents"></a> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> +
The files included are taken from formal builds of previous versions of QEMU, going back to 2.0.0 - qemu-doc.html - qemu-qmp-ref.html - qemu-ga-ref.html To import them all content outside of <body></body> is stripped and replaced by a trivial jekyll header. This causes the rendered docs to get consistent styling and navbar heading. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- This patch shows what it would be like if we just copied the pre-rendered QEMU docs into qemu-web for each major release.... ...it would be large. 2.0.0 was only 300 KB in size, but latest 3.0.0 release has 1.3 MB of docs. So we'd be adding about 4 MB of docs to qemu-web each year if we committed them. This feels undesirable as a strategy. I trimmed this mail to cut out the .html files to avoid spamming the list. If you want to see the full commit it is here: https://github.com/berrange/qemu-web/commit/c5f6d0f8664d7edd016f469f0709caec8360f783 At least in terms of the end result for users, I think it is positive. Other ideas 1. Upload built docs to a lookaside directory on the download site when making a release, then have a jekyll plugin to pull them in. Extra work for the person making releases principally. 2. Have a jekyll plugin that uses docker env to build each release docs from pristine tarballs. Would need caching to avoid burning CPU cycles in each web update. Reliably building older QEMU versions gets increasingly troublesome assets/css/style.css | 14 + documentation.md | 78 +- reference/2.0.0/qemu-doc.html | 7323 +++++++++ reference/2.1.0/qemu-doc.html | 7567 ++++++++++ reference/2.10.0/qemu-doc.html | 10026 +++++++++++++ reference/2.10.0/qemu-ga-ref.html | 1947 +++ reference/2.10.0/qemu-qmp-ref.html | 18766 +++++++++++++++++++++++ reference/2.11.0/qemu-doc.html | 10128 +++++++++++++ reference/2.11.0/qemu-ga-ref.html | 1993 +++ reference/2.11.0/qemu-qmp-ref.html | 19171 ++++++++++++++++++++++++ reference/2.12.0/qemu-doc.html | 10555 +++++++++++++ reference/2.12.0/qemu-ga-ref.html | 1931 +++ reference/2.12.0/qemu-qmp-ref.html | 20616 +++++++++++++++++++++++++ reference/2.2.0/qemu-doc.html | 7622 ++++++++++ reference/2.3.0/qemu-doc.html | 7692 ++++++++++ reference/2.4.0/qemu-doc.html | 7812 ++++++++++ reference/2.5.0/qemu-doc.html | 8300 +++++++++++ reference/2.6.0/qemu-doc.html | 8647 +++++++++++ reference/2.7.0/qemu-doc.html | 8771 +++++++++++ reference/2.8.0/qemu-doc.html | 9097 ++++++++++++ reference/2.9.0/qemu-doc.html | 9209 ++++++++++++ reference/2.9.0/qemu-ga-ref.html | 1693 +++ reference/2.9.0/qemu-qmp-ref.html | 18082 ++++++++++++++++++++++ reference/3.0.0/qemu-doc.html | 10810 ++++++++++++++ reference/3.0.0/qemu-ga-ref.html | 1939 +++ reference/3.0.0/qemu-qmp-ref.html | 21458 +++++++++++++++++++++++++++ 26 files changed, 231246 insertions(+), 1 deletion(-) create mode 100644 reference/2.0.0/qemu-doc.html create mode 100644 reference/2.1.0/qemu-doc.html create mode 100644 reference/2.10.0/qemu-doc.html create mode 100644 reference/2.10.0/qemu-ga-ref.html create mode 100644 reference/2.10.0/qemu-qmp-ref.html create mode 100644 reference/2.11.0/qemu-doc.html create mode 100644 reference/2.11.0/qemu-ga-ref.html create mode 100644 reference/2.11.0/qemu-qmp-ref.html create mode 100644 reference/2.12.0/qemu-doc.html create mode 100644 reference/2.12.0/qemu-ga-ref.html create mode 100644 reference/2.12.0/qemu-qmp-ref.html create mode 100644 reference/2.2.0/qemu-doc.html create mode 100644 reference/2.3.0/qemu-doc.html create mode 100644 reference/2.4.0/qemu-doc.html create mode 100644 reference/2.5.0/qemu-doc.html create mode 100644 reference/2.6.0/qemu-doc.html create mode 100644 reference/2.7.0/qemu-doc.html create mode 100644 reference/2.8.0/qemu-doc.html create mode 100644 reference/2.9.0/qemu-doc.html create mode 100644 reference/2.9.0/qemu-ga-ref.html create mode 100644 reference/2.9.0/qemu-qmp-ref.html create mode 100644 reference/3.0.0/qemu-doc.html create mode 100644 reference/3.0.0/qemu-ga-ref.html create mode 100644 reference/3.0.0/qemu-qmp-ref.html [...snip...]