From: "Daniel P. Berrangé" <berrange@redhat.com>
To: "Marc-André Lureau" <marcandre.lureau@gmail.com>
Cc: QEMU <qemu-devel@nongnu.org>, Paolo Bonzini <pbonzini@redhat.com>,
Thomas Huth <thuth@redhat.com>
Subject: Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
Date: Tue, 4 Dec 2018 10:19:57 +0000 [thread overview]
Message-ID: <20181204101957.GC20360@redhat.com> (raw)
In-Reply-To: <CAJ+F1CLr=JgtRqc6rC6N2Xe+YOchNkzryV4NB+sU-BWAUzPOsA@mail.gmail.com>
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 :|
next prev parent reply other threads:[~2018-12-04 10:20 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
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é [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181204101957.GC20360@redhat.com \
--to=berrange@redhat.com \
--cc=marcandre.lureau@gmail.com \
--cc=pbonzini@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=thuth@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.