[PATCH 0/7] docs: css: Tweak appearance of documents converted from RST
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/kbase... Above with grey box: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/668221137/artifacts/website/kbase... 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/kbase... 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
'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@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
On a Monday in 2020, Peter Krempa wrote:
'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'
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@redhat.com> --- docs/manpages/meson.build | 2 +- docs/meson.build | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
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@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
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@redhat.com> --- docs/generic.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
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@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
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@redhat.com> --- docs/libvirt.css | 7 +++++++ 1 file changed, 7 insertions(+)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
'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@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
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@redhat.com> --- docs/libvirt.css | 4 ++++ 1 file changed, 4 insertions(+)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Emphasise the table of contents visually. Signed-off-by: Peter Krempa <pkrempa@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
On a Monday in 2020, Peter Krempa wrote:
Emphasise the table of contents visually.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)
test $(( $RANDOM % 2 )) == 0 || echo "Reviewed-by: Ján Tomko <jtomko@redhat.com>" Jano
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@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
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@redhat.com> --- docs/kbase.rst | 2 +- docs/libvirt.css | 20 ++++++++------------ 2 files changed, 9 insertions(+), 13 deletions(-)
Jano
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.
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
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 :|
Signed-off-by: Peter Krempa <pkrempa@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
participants (3)
-
Daniel P. Berrangé -
Ján Tomko -
Peter Krempa