[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation
|
From: |
Daniel P . Berrangé |
|
Subject: |
Re: [Qemu-devel] [qemu-web PATCH] Import historical documentation |
|
Date: |
Tue, 4 Dec 2018 10:19:57 +0000 |
|
User-agent: |
Mutt/1.10.1 (2018-07-13) |
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é <address@hidden> 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é <address@hidden>
>
> Nice! Except the minor link issue of 2.11,
>
> Reviewed-by: Marc-André Lureau <address@hidden>
>
> > ---
> >
> > 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 :|