6:53 a.m.
Note that patch 5 is just RFC. It can be dropped if we don't want to add
the gray background.
Here are the options for the ToC separation done by patches 3-5:
Current state:
https://libvirt.org/kbase/debuglogs.html
With just separation of the ToC and 'Contents:' hidden:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/667749501/artifacts/website/kb...
Above with grey box:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/668221137/artifacts/website/kb...
Patch 6 then modifies the 'kbase' article directory:
Current state:
https://libvirt.org/kbase.html
New state:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/668221137/artifacts/website/kb...
Peter Krempa (7):
docs: build: Don't include stylesheet in intermediate html files
generated from RST
docs: css: Make definition list 'code' entries bold when converted
from rst
docs: css: Add separation for table of contents generated from RST
docs: css: Hide redundant 'Contents:' line in table of contents of RST
docs
docs: css: Add a gray box around table of contents of RST based docs
docs: css: Modify appearance of the kbase directory page
docs: kbase: Remove unused 'container'
docs/generic.css | 2 +-
docs/kbase.rst | 60 +++++++++++++++++++--------------------
docs/libvirt.css | 35 +++++++++++++++--------
docs/manpages/meson.build | 2 +-
docs/meson.build | 2 +-
5 files changed, 55 insertions(+), 46 deletions(-)
--
2.26.2
6:53 a.m.
New subject: [PATCH 1/7] docs: build: Don't include stylesheet in intermediate html files generated from RST
'docutils' add a stylesheet to the output html file for direct
consumption. Since we use the html files just as an intermediate step
which is post-processed to add our own stylesheet and drop the docutils
one in the process we can ask 'rst2html' to not add any for a
intermediate file with less garbage.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/manpages/meson.build | 2 +-
docs/meson.build | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
index e9d9ac8069..97133adf3a 100644
--- a/docs/manpages/meson.build
+++ b/docs/manpages/meson.build
@@ -99,7 +99,7 @@ foreach data : docs_man_files
html_in_file,
input: rst_file,
output: html_in_file,
- command: [ rst2html_prog, '--strict', '@INPUT@' ],
+ command: [ rst2html_prog, '--stylesheet=', '--strict',
'@INPUT@' ],
capture: true,
)
diff --git a/docs/meson.build b/docs/meson.build
index 2f06e8eace..a98147f7fd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -188,7 +188,7 @@ docs_admin_api_xml = docs_api_generated[3]
docs_rst2html_gen = generator(
rst2html_prog,
output: '@BASENAME@.html.in',
- arguments: [ '--strict', '@INPUT@' ],
+ arguments: [ '--stylesheet=', '--strict', '@INPUT@' ],
capture: true,
)
--
2.26.2
7:22 a.m.
New subject: [PATCH 1/7] docs: build: Don't include stylesheet in intermediate html files generated from RST
On a Monday in 2020, Peter Krempa wrote:
Hmm,
Minimal style sheet for the HTML output of Docutils
does not look minimal to me:
"docs/kbase.html.p/kbase.html.in" 610L, 16789B 557,1
93%
>Signed-off-by: Peter Krempa <pkrempa(a)redhat.com >---
> docs/manpages/meson.build | 2 +-
> docs/meson.build | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com
Jano
'docutils' add a stylesheet to the output html file for
direct
consumption. Since we use the html files just as an intermediate step
which is post-processed to add our own stylesheet and drop the docutils
one in the process we can ask 'rst2html' to not add any for a
intermediate file with less garbage.
'an intermediate'
6:53 a.m.
New subject: [PATCH 2/7] docs: css: Make definition list 'code' entries bold when converted from rst
Docutils don't generate <code> for inline literals (``blah``) in rst
but rather put them in the '.literal' class. Add a selector for making
them bold when used in definition list headers.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/generic.css | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/generic.css b/docs/generic.css
index c4092abc2b..d15d85e67a 100644
--- a/docs/generic.css
+++ b/docs/generic.css
@@ -25,7 +25,7 @@ dt {
margin-right: 2em;
}
-dt code {
+dt code, dt .literal {
font-weight: bold;
}
--
2.26.2
7:24 a.m.
New subject: [PATCH 2/7] docs: css: Make definition list 'code' entries bold when converted from rst
On a Monday in 2020, Peter Krempa wrote:
Docutils don't generate <code> for inline literals
(``blah``) in rst
but rather put them in the '.literal' class. Add a selector for making
them bold when used in definition list headers.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/generic.css | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
6:53 a.m.
New subject: [PATCH 3/7] docs: css: Add separation for table of contents generated from RST
The table of contents of documents generated from RST is quite squeezed
together. Add 2em-s worth of vertical separation on each side.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 551adac2f2..6b1e86c7d8 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -590,3 +590,10 @@ th p, td p {
margin-top: 0px;
margin-bottom: 0px;
}
+
+/* Elements with id 'contents' contain the table of contents generated by
docutils */
+
+#contents {
+ margin-top: 2em;
+ margin-bottom: 2em;
+}
--
2.26.2
7:24 a.m.
New subject: [PATCH 3/7] docs: css: Add separation for table of contents generated from RST
On a Monday in 2020, Peter Krempa wrote:
The table of contents of documents generated from RST is quite
squeezed
together. Add 2em-s worth of vertical separation on each side.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 7 +++++++
1 file changed, 7 insertions(+)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
6:53 a.m.
New subject: [PATCH 4/7] docs: css: Hide redundant 'Contents:' line in table of contents of RST docs
'docutils' add line saying "Contents:" on top of the table of contents.
We don't have that in other documents nor it's really necessary. Hide it
in the stylesheet as we can select it easily.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 6b1e86c7d8..4dc9d3ac76 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -597,3 +597,7 @@ th p, td p {
margin-top: 2em;
margin-bottom: 2em;
}
+
+#contents p.topic-title {
+ display: none;
+}
--
2.26.2
7:25 a.m.
New subject: [PATCH 4/7] docs: css: Hide redundant 'Contents:' line in table of contents of RST docs
On a Monday in 2020, Peter Krempa wrote:
'docutils' add line saying "Contents:" on top of the
table of contents.
We don't have that in other documents nor it's really necessary. Hide it
in the stylesheet as we can select it easily.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 4 ++++
1 file changed, 4 insertions(+)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
6:53 a.m.
New subject: [PATCH 5/7] docs: css: Add a gray box around table of contents of RST based docs
Emphasise the table of contents visually.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 4dc9d3ac76..3d94029787 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -594,8 +594,12 @@ th p, td p {
/* Elements with id 'contents' contain the table of contents generated by
docutils */
#contents {
- margin-top: 2em;
- margin-bottom: 2em;
+ margin-top: 1em;
+ margin-bottom: 1em;
+ background: rgb(230, 230, 230);
+ padding: 0.5em;
+ padding-left: 0px;
+ display: inline-block;
}
#contents p.topic-title {
--
2.26.2
7:28 a.m.
New subject: [PATCH 5/7] docs: css: Add a gray box around table of contents of RST based docs
On a Monday in 2020, Peter Krempa wrote:
Emphasise the table of contents visually.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/libvirt.css | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
test $(( $RANDOM % 2 )) == 0 || echo "Reviewed-by: Ján Tomko
<jtomko(a)redhat.com>"
Jano
6:53 a.m.
New subject: [PATCH 6/7] docs: css: Modify appearance of the kbase directory page
Remove the gray background and switch to underlined links.
This change is done by using the fact that docutils name the top level
element based on the pagee name. This means that in the stylesheet we
can apply selectors directly to the specific page.
This removes the need to have a RST 'container' named 'panel' in the
file.
Specific selectors are used only for elements on the directory page.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase.rst | 2 +-
docs/libvirt.css | 20 ++++++++------------
2 files changed, 9 insertions(+), 13 deletions(-)
diff --git a/docs/kbase.rst b/docs/kbase.rst
index 78daaa5989..8f888c27cd 100644
--- a/docs/kbase.rst
+++ b/docs/kbase.rst
@@ -2,7 +2,7 @@
Knowledge base
==============
-.. container:: panel widepanel
+.. container::
`Debug logs <kbase/debuglogs.html>`__
Configuration of logging and tips on how to file a good bug report.
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 3d94029787..01627f2113 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -402,14 +402,6 @@ div.panel {
background: rgb(230, 230, 230);
}
-div.widepanel {
- width: 70em;
- max-width: 95%;
- margin-left: 0px;
- float: left;
- background: rgb(230, 230, 230);
-}
-
div.panel h2 {
margin-top: 0px;
padding: 0.5em;
@@ -479,7 +471,8 @@ br.clear {
font-size: smaller;
}
-div.panel dd {
+div.panel dd,
+#knowledge-base dd {
font-size: smaller;
}
@@ -489,7 +482,8 @@ div.panel a {
div.panel ul,
div.panel p,
-div.panel dl {
+div.panel dl,
+#knowledge-base p {
padding: 0.5em;
margin: 0px;
}
@@ -498,10 +492,12 @@ div.panel dl {
div.panel ul {
margin-left: 1em;
}
-div.panel dt {
+div.panel dt,
+#knowledge-base dt {
margin: 0px;
}
-div.panel dd {
+div.panel dd,
+#knowledge-base dd {
margin: 0px;
margin-bottom: 1em;
}
--
2.26.2
7:30 a.m.
New subject: [PATCH 6/7] docs: css: Modify appearance of the kbase directory page
On a Monday in 2020, Peter Krempa wrote:
Remove the gray background and switch to underlined links.
Here, I prefer the old look. The difference with the ToC might be
that the ToC entries are indented.
This change is done by using the fact that docutils name the top
level
element based on the pagee name. This means that in the stylesheet we
*page
can apply selectors directly to the specific page.
This removes the need to have a RST 'container' named 'panel' in the
file.
Specific selectors are used only for elements on the directory page.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase.rst | 2 +-
docs/libvirt.css | 20 ++++++++------------
2 files changed, 9 insertions(+), 13 deletions(-)
Jano
7:39 a.m.
New subject: [PATCH 6/7] docs: css: Modify appearance of the kbase directory page
On Mon, Aug 03, 2020 at 14:30:30 +0200, Ján Tomko wrote:
On a Monday in 2020, Peter Krempa wrote:
> Remove the gray background and switch to underlined links.
>
Here, I prefer the old look. The difference with the ToC might be
that the ToC entries are indented.
Both links and background? In case you prefer the old links I might want
to get rid of the background at least.
6:13 a.m.
New subject: [PATCH 6/7] docs: css: Modify appearance of the kbase directory page
On a Monday in 2020, Peter Krempa wrote:
On Mon, Aug 03, 2020 at 14:30:30 +0200, Ján Tomko wrote:
> On a Monday in 2020, Peter Krempa wrote:
> > Remove the gray background and switch to underlined links.
> >
>
> Here, I prefer the old look. The difference with the ToC might be
> that the ToC entries are indented.
Both links and background? In case you prefer the old links I might want
to get rid of the background at least.
Sorry, I only compared the overall look.
After some experimenting, what concerns me most is the spacing:
In the old version the gray panel aligns with the 'Knowledge base'
heading.
In the white one, the K aligns with 'Debug logs' and it's too close
to the heading.
So I miss mostly:
padding: 0.5 em;
that came from the panel.
1. I'm okay with dropping the gray background, since the kbase page is
different. (The bikeshedding question is: will we eventually fill it
enough to warrant a return of the gray panels and put three of them
on a computer screen?)
2. The 0.5 em padding should stay (I guess keeping another panel class
for this makes sense then.
3. The links look slightly better and more consistent with the rest of
the website with text-decoration: none; but I don't have a strong
preference here - we do have underlined links on white background
elsewhere.
Unrelated to this patch:
4. We have a 0.5 em padding for both `div.panel dl` and `div.panel p`,
which add up to 1 em for the paragraphs inside `dd`. Since what
we're adding there should be a one-sentence description of the document,
can we somehow convince the rst tools not to put a paragraph there?
Or just adjust the padding back for `div.panel p dd`? HTML, I'll be
missing you.
Jano
6:18 a.m.
New subject: [PATCH 6/7] docs: css: Modify appearance of the kbase directory page
On Tue, Aug 04, 2020 at 01:13:16PM +0200, Ján Tomko wrote:
On a Monday in 2020, Peter Krempa wrote:
> On Mon, Aug 03, 2020 at 14:30:30 +0200, Ján Tomko wrote:
> > On a Monday in 2020, Peter Krempa wrote:
> > > Remove the gray background and switch to underlined links.
> > >
> >
> > Here, I prefer the old look. The difference with the ToC might be
> > that the ToC entries are indented.
>
> Both links and background? In case you prefer the old links I might want
> to get rid of the background at least.
>
Sorry, I only compared the overall look.
After some experimenting, what concerns me most is the spacing:
In the old version the gray panel aligns with the 'Knowledge base'
heading.
In the white one, the K aligns with 'Debug logs' and it's too close
to the heading.
So I miss mostly:
padding: 0.5 em;
that came from the panel.
1. I'm okay with dropping the gray background, since the kbase page is
different. (The bikeshedding question is: will we eventually fill it
enough to warrant a return of the gray panels and put three of them
on a computer screen?)
As we migrate the wiki content it'll mostly end up in the kbase, and
I expect we'll want to split the kbase index into a series of groups
with panels, like we do for the main docs page and front page. This
was the main reason why I had the page rendered the way it currently
is.
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 :|
6:53 a.m.
New subject: [PATCH 7/7] docs: kbase: Remove unused 'container'
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase.rst | 60 ++++++++++++++++++++++++--------------------------
1 file changed, 29 insertions(+), 31 deletions(-)
diff --git a/docs/kbase.rst b/docs/kbase.rst
index 8f888c27cd..6f3740f941 100644
--- a/docs/kbase.rst
+++ b/docs/kbase.rst
@@ -2,45 +2,43 @@
Knowledge base
==============
-.. container::
+`Debug logs <kbase/debuglogs.html>`__
+ Configuration of logging and tips on how to file a good bug report.
- `Debug logs <kbase/debuglogs.html>`__
- Configuration of logging and tips on how to file a good bug report.
+`Disk locking <kbase/locking.html>`__
+ Ensuring exclusive guest access to disks with
+ `virtlockd <kbase/locking-lockd.html>`__ or
+ `Sanlock <kbase/locking-sanlock.html>`__
- `Disk locking <kbase/locking.html>`__
- Ensuring exclusive guest access to disks with
- `virtlockd <kbase/locking-lockd.html>`__ or
- `Sanlock <kbase/locking-sanlock.html>`__
+`Secure usage <kbase/secureusage.html>`__
+ Secure usage of the libvirt APIs
- `Secure usage <kbase/secureusage.html>`__
- Secure usage of the libvirt APIs
+`Protected virtualization on s390 <kbase/s390_protected_virt.html>`__
+ Running secure s390 guests with IBM Secure Execution
- `Protected virtualization on s390 <kbase/s390_protected_virt.html>`__
- Running secure s390 guests with IBM Secure Execution
+`Launch security <kbase/launch_security_sev.html>`__
+ Securely launching VMs with AMD SEV
- `Launch security <kbase/launch_security_sev.html>`__
- Securely launching VMs with AMD SEV
+`Domain state capture <kbase/domainstatecapture.html>`__
+ Comparison between different methods of capturing domain state
- `Domain state capture <kbase/domainstatecapture.html>`__
- Comparison between different methods of capturing domain state
+`RPM deployment <kbase/rpm-deployment.html>`__
+ Explanation of the different RPM packages and illustration of which to
+ pick for installation
- `RPM deployment <kbase/rpm-deployment.html>`__
- Explanation of the different RPM packages and illustration of which to
- pick for installation
+`Backing chain management <kbase/backing_chains.html>`__
+ Explanation of how disk backing chain specification impacts libvirt's
+ behaviour and basic troubleshooting steps of disk problems.
- `Backing chain management <kbase/backing_chains.html>`__
- Explanation of how disk backing chain specification impacts libvirt's
- behaviour and basic troubleshooting steps of disk problems.
+`Security with QEMU passthrough <kbase/qemu-passthrough-security.html>`__
+ Examination of the security protections used for QEMU and how they need
+ configuring to allow use of QEMU passthrough with host files/devices.
- `Security with QEMU passthrough <kbase/qemu-passthrough-security.html>`__
- Examination of the security protections used for QEMU and how they need
- configuring to allow use of QEMU passthrough with host files/devices.
+`Virtio-FS <kbase/virtiofs.html>`__
+ Share a filesystem between the guest and the host
- `Virtio-FS <kbase/virtiofs.html>`__
- Share a filesystem between the guest and the host
+`KVM real time <kbase/kvm-realtime.html>`__
+ Run real time workloads in guests on a KVM hypervisor
- `KVM real time <kbase/kvm-realtime.html>`__
- Run real time workloads in guests on a KVM hypervisor
-
- `Incremental backup internals <kbase/incrementalbackupinternals.html>`__
- Incremental backup implementation details relevant for users
+`Incremental backup internals <kbase/incrementalbackupinternals.html>`__
+ Incremental backup implementation details relevant for users
--
2.26.2
1571
days inactive
1572
days old
16 comments
3 participants
participants (3)
-
Daniel P. Berrangé -
Ján Tomko -
Peter Krempa