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 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).