From 4db42c1c7f45fb1bc2efd3355eb7ac34d3bc0ffb Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Thu, 21 May 2020 13:22:02 -0700 Subject: [PATCH] doc: fix rst-columns display Using ``.. rst-class:: rst-columns`` wasn't processed correctly because of an error in the acrn-custom.css file. Fix that, update the documentation guidelines, and make use of the multi-column display in documents where the toctree created a long list. Now it will appear in columns. Also tweaked the toctree listing to use bold for the first-level items (making a multi-column display look better, particularly when it has subsections). Signed-off-by: David B. Kinder --- doc/contribute.rst | 4 ++++ doc/develop.rst | 16 ++++++++++++---- doc/developer-guides/doc_guidelines.rst | 9 +++++---- doc/developer-guides/hld/index.rst | 2 ++ doc/release_notes/index.rst | 2 ++ doc/static/acrn-custom.css | 11 +++++++++-- 6 files changed, 34 insertions(+), 10 deletions(-) diff --git a/doc/contribute.rst b/doc/contribute.rst index 174d6e8a8..250ca08f0 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -15,6 +15,8 @@ Read about ACRN's high-level design and architecture principles that led to the development of the ACRN hypervisor and its components. You'll also find details about specific architecture topics. +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -36,6 +38,8 @@ project. Here's where you'll find how the development team works and the guidelines they (and you) use to contribute code (and documentation) to the project. +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 diff --git a/doc/develop.rst b/doc/develop.rst index cf39d23db..a8d407e2d 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -7,6 +7,8 @@ Advanced Guides Configuration and Tools *********************** +.. rst-class:: rst-columns2 + .. toctree:: :glob: :maxdepth: 1 @@ -23,6 +25,8 @@ Configuration and Tools Service VM Tutorials ******************** +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -32,6 +36,8 @@ Service VM Tutorials User VM Tutorials ***************** +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -48,6 +54,8 @@ User VM Tutorials Enable ACRN Features ******************** +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -70,6 +78,8 @@ Enable ACRN Features Debug ***** +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -80,6 +90,8 @@ Debug Additional Tutorials ******************** +.. rst-class:: rst-columns2 + .. toctree:: :maxdepth: 1 @@ -91,7 +103,3 @@ Additional Tutorials tutorials/sign_clear_linux_image tutorials/enable_laag_secure_boot tutorials/kbl-nuc-sdc - - - - diff --git a/doc/developer-guides/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst index 86c0c9aca..cec7b8253 100644 --- a/doc/developer-guides/doc_guidelines.rst +++ b/doc/developer-guides/doc_guidelines.rst @@ -197,10 +197,11 @@ would be rendered as: * space on * the page -A maximum of three columns will be displayed, and change based on the -available width of the display window, reducing to one column on narrow -(phone) screens if necessary. We've deprecated use of the ``hlist`` -directive because it misbehaves on smaller screens. +A maximum of three columns will be displayed if you use ``rst-columns`` +or ``rst-columns3`` (and two columns for ``rst-columns2``), and change +based on the available width of the display window, reducing to one +column on narrow (phone) screens if necessary. We've deprecated use of +the ``hlist`` directive because it misbehaves on smaller screens. Tables ****** diff --git a/doc/developer-guides/hld/index.rst b/doc/developer-guides/hld/index.rst index 49ff32ed8..1efffb931 100644 --- a/doc/developer-guides/hld/index.rst +++ b/doc/developer-guides/hld/index.rst @@ -13,6 +13,8 @@ These chapters describe the ACRN architecture, high-level design, background, and motivation for specific areas within the ACRN hypervisor system. +.. rst-class:: rst-columns + .. toctree:: :maxdepth: 2 diff --git a/doc/release_notes/index.rst b/doc/release_notes/index.rst index 34befceac..961289f5f 100644 --- a/doc/release_notes/index.rst +++ b/doc/release_notes/index.rst @@ -12,6 +12,8 @@ The project ACRN reference code can be found on GitHub in https://github.com/projectacrn. It includes the ACRN hypervisor, the ACRN device model, and documentation. +.. rst-class:: rst-columns + .. toctree:: :maxdepth: 1 :glob: diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css index 96bad623c..044383d0a 100644 --- a/doc/static/acrn-custom.css +++ b/doc/static/acrn-custom.css @@ -5,7 +5,7 @@ max-width: 1100px; } -/* (temporarily) add an under development tagline to the bread crumb +/* (temporarily) add an under development tagline to the bread crumb .wy-breadcrumbs::after { content: " (Content reorganization in progress)"; background-color: #FFFACD; @@ -266,10 +266,12 @@ kbd .rst-columns2 { column-width: 28em; column-fill: balance; + margin-bottom: 1em; } -.rst-columns3 .rst-columns { +.rst-columns3, .rst-columns { column-width: 18em; column-fill: balance; + margin-bottom: 1em; } /* numbered "h2" steps */ @@ -292,3 +294,8 @@ div.numbered-step h2::before { margin-right: 5px; text-align: center; width: 1.6em;} + +/* bold the level1 headings in on-page toctree displays */ +.rst-content .toctree-l1 > a { + font-weight: bold; +}