Help: Add responsive layout for small screens
These changes activate only on small screens, where "small" is defined
as <=760px, i.e. anything smaller than iPad Mini.
* Turn the sidebar into a popup (on the right) and add a hamburger
button in the header to show it.
* Split the header and footer into two lines, make the header sticky.
* Remove the prev/next links from the header.
* Put the search box first in the sidebar.
* Disable horizontal scroll of the page, enable individual scrolling
for h1, table. (Code blocks already have it).
* Allow line breaking of overly long words in the document body.
* Adjust various margins.
The sidebar popup works without JavaScript (using the "checkbox hack"),
but a bit of JavaScript is added to enable automatic closing on Esc,
on a link click and on document navigation.
diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css
index b4dcb32..72b8060 100644
--- a/Utilities/Sphinx/static/cmake.css
+++ b/Utilities/Sphinx/static/cmake.css
@@ -118,3 +118,212 @@
table.docutils td {
border-top: 1px solid #aaa;
}
+
+/* Hide small screen specific items */
+#sidebar-toggle,
+#sidebar-check,
+#sidebar-overlay {
+ display: none;
+}
+
+/* Small screen overrides */
+@media screen and (max-width: 760px) {
+
+ /* Sticky header */
+ div.relbar1 {
+ position: sticky;
+ top: 0;
+ z-index: 10;
+ }
+
+ html {
+ scroll-padding-top: 56px;
+ }
+
+ /* Header and footer */
+ div.related {
+ line-height: 28px;
+ }
+
+ div.related ul {
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ }
+
+ div.related li.right {
+ display: none;
+ }
+
+ div.related li.rootlink {
+ display: block;
+ margin-bottom: -1px;
+ }
+
+ div.related span.reldelim1 {
+ display: none;
+ }
+
+ /* Popup sidebar */
+ div.sphinxsidebar {
+ background-color: #e4ece8;
+ margin-left: 0;
+ position: fixed;
+ top: 0;
+ right: 0;
+ width: 260px;
+ height: 100%;
+ overflow-y: scroll;
+ z-index: 30;
+ visibility: hidden;
+ transform: translateX(100%);
+ transition: transform 0.2s ease-out, visibility 0.2s;
+ }
+
+ #sidebar-check:checked ~ div.document div.sphinxsidebar {
+ visibility: visible;
+ transform: none;
+ }
+
+ div.sphinxsidebarwrapper {
+ padding-bottom: 10px;
+ display: flex;
+ flex-direction: column;
+ }
+
+ /* Put the search box first in the sidebar. */
+ #searchbox {
+ order: -1;
+ margin-bottom: 10px;
+ }
+
+ /* Popup sidebar overlay */
+ #sidebar-overlay {
+ display: block;
+ position: fixed;
+ top: 0;
+ width: 100%;
+ height: 200%;
+ background-color: #000;
+ z-index: 20;
+ visibility: hidden;
+ opacity: 0;
+ transition: opacity 0.2s ease-out, visibility 0.2s;
+ }
+
+ #sidebar-check:checked ~ #sidebar-overlay {
+ visibility: visible;
+ opacity: 0.5;
+ }
+
+ /* Popup sidebar button */
+ label.sidebar-toggle {
+ display: block;
+ float: right;
+ position: relative;
+ cursor: pointer;
+ width: 48px;
+ height: 56px;
+ background: no-repeat center/24px url("data:image/svg+xml,\
+ %3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath\
+ d='M3,6H21 M3,12H21 M3,18H21' fill='none' stroke='white' stroke-width='2'\
+ stroke-linecap='square' /%3E%3C/svg%3E");
+ }
+
+ /* Force-wrap long words */
+ div.body span.pre {
+ white-space: pre-wrap;
+ }
+
+ /* Disable whole page horizontal scroll, enable selectively. */
+ div.body {
+ min-width: auto;
+ overflow-x: hidden;
+ overflow-wrap: break-word;
+ }
+
+ div.body h1 {
+ white-space: nowrap;
+ overflow-x: auto;
+ }
+
+ table.docutils {
+ display: block;
+ overflow-x: auto;
+ }
+
+ /* Adjust various margins */
+ div.bodywrapper {
+ margin: 0;
+ }
+
+ div.body {
+ padding: 0 12px 12px;
+ }
+
+ div.body h1,
+ div.body h2,
+ div.body h3,
+ div.body h4,
+ div.body h5,
+ div.body h6 {
+ margin: 20px -12px 10px;
+ padding: 3px 0px 3px 12px;
+ }
+
+ div.body h1 {
+ margin-top: 0;
+ }
+
+ div.body ul {
+ padding-left: 15px;
+ }
+
+ div.body dd {
+ margin-left: 10px;
+ }
+
+ div.sphinxsidebar h4 {
+ margin: 0;
+ }
+
+ div.sphinxsidebar ul {
+ margin: 5px 0 10px 10px;
+ }
+
+ div.sphinxsidebar ul ul {
+ margin: 0 0 0 10px;
+ }
+
+ div.sphinxsidebar li {
+ margin-top: 5px;
+ }
+
+ div.deprecated > *,
+ div.versionadded > *,
+ div.versionchanged > * {
+ padding-left: 10px;
+ }
+
+ div.deprecated > :first-child,
+ div.versionadded > :first-child,
+ div.versionchanged > :first-child {
+ text-indent: -10px;
+ }
+
+ a.headerlink {
+ display: none;
+ }
+
+ /* Make index single-column. */
+ table.indextable,
+ table.indextable tbody,
+ table.indextable tr,
+ table.indextable td {
+ display: block;
+ }
+
+ table.indextable td {
+ width: auto !important;
+ }
+}
diff --git a/Utilities/Sphinx/templates/layout.html b/Utilities/Sphinx/templates/layout.html
index e783a2d..b536b06 100644
--- a/Utilities/Sphinx/templates/layout.html
+++ b/Utilities/Sphinx/templates/layout.html
@@ -1,5 +1,8 @@
{% extends "!layout.html" %}
{% block rootrellink %}
+ <li>
+ <label class="sidebar-toggle" for="sidebar-check"></label>
+ </li>
<li class="rootlink">
<img src="{{ pathto('_static/cmake-logo-16.png', 1) }}" width="16" height="16" alt=""/>
{%- if versionswitch is defined %}
@@ -7,7 +10,7 @@
{%- else %}
<a href="https://cmake.org/">CMake {{ release }}</a>
{%- endif %}
- {{ reldelim1 }}
+ <span class="reldelim1">{{ reldelim1 }}</span>
</li>
<li>
<a href="{{ pathto(master_doc) }}">{% trans %}Documentation{% endtrans %}</a>{{ reldelim1 }}
@@ -15,7 +18,7 @@
{% endblock %}
{%- block relbar1 %}
-{{ super() }}
+{{ super()|replace('class="related"', 'class="related relbar1"') }}
{%- if outdated is defined %}
<div class="outdated">
This documents an old version of CMake.
@@ -45,6 +48,14 @@
<title>{{ title|striptags|e }} {{ "—"|safe }} {{ docstitle|e }}</title>
{% endblock %}
+{%- block header %}
+{%- if render_sidebar %}
+ <input id="sidebar-check" type="checkbox" />
+ <label id="sidebar-overlay" for="sidebar-check"></label>
+{%- endif %}
+{{ super() }}
+{% endblock %}
+
{%- block footer %}
{{ super() }}
{%- if googleanalytics is defined %}
@@ -59,4 +70,15 @@
} catch(err) {}
</script>
{%- endif %}
+{%- if render_sidebar %}
+<script type="text/javascript">
+(function() {
+ "use strict";
+ const hide = () => document.getElementById("sidebar-check").checked = false;
+ addEventListener("keydown", e => (e.key === "Escape") && hide());
+ addEventListener("click", e => (e.target.tagName === "A") && hide());
+ addEventListener("hashchange", hide)
+})();
+</script>
+{%- endif %}
{%- endblock %}
