* [Qemu-devel] [qemu-web PATCH] Import historical documentation
@ 2018-12-03 16:41 Daniel P. Berrangé
2018-12-03 19:14 ` Marc-André Lureau
2018-12-04 10:56 ` Thomas Huth
0 siblings, 2 replies; 7+ messages in thread
From: Daniel P. Berrangé @ 2018-12-03 16:41 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Thomas Huth, Daniel P. Berrangé
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
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">
+
[...snip...]
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-03 16:41 [Qemu-devel] [qemu-web PATCH] Import historical documentation Daniel P. Berrangé
@ 2018-12-03 19:14 ` Marc-André Lureau
2018-12-04 10:19 ` Daniel P. Berrangé
2018-12-04 10:56 ` Thomas Huth
1 sibling, 1 reply; 7+ messages in thread
From: Marc-André Lureau @ 2018-12-03 19:14 UTC (permalink / raw)
To: Daniel P. Berrange; +Cc: QEMU, Paolo Bonzini, Thomas Huth
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...]
>
--
Marc-André Lureau
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-03 19:14 ` Marc-André Lureau
@ 2018-12-04 10:19 ` Daniel P. Berrangé
0 siblings, 0 replies; 7+ messages in thread
From: Daniel P. Berrangé @ 2018-12-04 10:19 UTC (permalink / raw)
To: Marc-André Lureau; +Cc: QEMU, Paolo Bonzini, Thomas Huth
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
--
|: 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] 7+ messages in thread
* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-03 16:41 [Qemu-devel] [qemu-web PATCH] Import historical documentation Daniel P. Berrangé
2018-12-03 19:14 ` Marc-André Lureau
@ 2018-12-04 10:56 ` Thomas Huth
2018-12-06 20:01 ` Paolo Bonzini
1 sibling, 1 reply; 7+ messages in thread
From: Thomas Huth @ 2018-12-04 10:56 UTC (permalink / raw)
To: Daniel P. Berrangé, qemu-devel; +Cc: Paolo Bonzini, Stefan Weil, Jeff Cody
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-04 10:56 ` Thomas Huth
@ 2018-12-06 20:01 ` Paolo Bonzini
2018-12-07 9:44 ` Daniel P. Berrangé
0 siblings, 1 reply; 7+ messages in thread
From: Paolo Bonzini @ 2018-12-06 20:01 UTC (permalink / raw)
To: Thomas Huth, Daniel P. Berrangé, qemu-devel
Cc: Stefan Weil, Jeff Cody, Michael Roth
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-06 20:01 ` Paolo Bonzini
@ 2018-12-07 9:44 ` Daniel P. Berrangé
2018-12-07 15:59 ` Michael Roth
0 siblings, 1 reply; 7+ messages in thread
From: Daniel P. Berrangé @ 2018-12-07 9:44 UTC (permalink / raw)
To: Paolo Bonzini
Cc: Thomas Huth, qemu-devel, Stefan Weil, Jeff Cody, Michael Roth
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
--
|: 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] 7+ messages in thread
* Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
2018-12-07 9:44 ` Daniel P. Berrangé
@ 2018-12-07 15:59 ` Michael Roth
0 siblings, 0 replies; 7+ messages in thread
From: Michael Roth @ 2018-12-07 15:59 UTC (permalink / raw)
To: Daniel P. Berrangé, Paolo Bonzini
Cc: Jeff Cody, Stefan Weil, Thomas Huth, qemu-devel
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 :|
>
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2018-12-07 15:59 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-12-03 16:41 [Qemu-devel] [qemu-web PATCH] Import historical documentation Daniel P. Berrangé
2018-12-03 19:14 ` Marc-André Lureau
2018-12-04 10:19 ` Daniel P. Berrangé
2018-12-04 10:56 ` Thomas Huth
2018-12-06 20:01 ` Paolo Bonzini
2018-12-07 9:44 ` Daniel P. Berrangé
2018-12-07 15:59 ` Michael Roth
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).