From bf9ccc84274ed002008d11f7fb101cd6d8320adf Mon Sep 17 00:00:00 2001
From: Nikita Nemkin <nikita@nemkin.ru>
Date: Sat, 1 Feb 2025 20:33:31 +0500
Subject: Help: Theme improvements

* Push the footer to the bottom of the page (for short pages).
* Remove the link from the sidebar "Table of Contents" header.
* Remove text justification from TOCs and tables.
* Adjust logo position in the header.
* Restructure the navigation bar from
    CMake >> [version] Documentation >> Page
  to
    CMake [version] >> Documentation >> Page
---
 Utilities/Sphinx/static/cmake.css        | 29 ++++++++++++++++++++++++++++-
 Utilities/Sphinx/templates/layout.html   | 19 ++++++++-----------
 Utilities/Sphinx/templates/localtoc.html |  8 ++++++++
 3 files changed, 44 insertions(+), 12 deletions(-)
 create mode 100644 Utilities/Sphinx/templates/localtoc.html

diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css
index 909b58a..b4dcb32 100644
--- a/Utilities/Sphinx/static/cmake.css
+++ b/Utilities/Sphinx/static/cmake.css
@@ -1,6 +1,28 @@
 /* Import the Sphinx theme style.  */
 @import url("default.css");
 
+/* Navbar logo */
+li.rootlink > img {
+  vertical-align: middle;
+  margin-top: -5px;
+}
+
+/* Push the footer to the bottom of the page. */
+body {
+  display: flex;
+  flex-direction: column;
+  min-height: 100svh;
+}
+
+div.document {
+  flex-grow: 1;
+}
+
+div.bodywrapper,
+div.body {
+  height: 100%;
+}
+
 /* Wrap sidebar content even within words so that long
    document names do not escape sidebar borders.  */
 div.sphinxsidebarwrapper {
@@ -17,6 +39,12 @@ div.sphinxsidebarwrapper {
   background-color: #dfdfdf;
 }
 
+/* Un-justify some elements. */
+div.body table.docutils p,
+div.body nav.contents p {
+  text-align: left;
+}
+
 /* Apply <pre> style (from classic.css) to signature directive argument. */
 .signature .sig {
   padding: 5px;
@@ -73,7 +101,6 @@ div.outdated {
   padding-right: 2px;
   padding-top: 5px;
   text-align: center;
-  width: 100%;
 }
 
 /* Revert style to the inherited (normal text) for `:guide:` links */
diff --git a/Utilities/Sphinx/templates/layout.html b/Utilities/Sphinx/templates/layout.html
index 8fb7c42..e783a2d 100644
--- a/Utilities/Sphinx/templates/layout.html
+++ b/Utilities/Sphinx/templates/layout.html
@@ -1,19 +1,16 @@
 {% extends "!layout.html" %}
 {% block rootrellink %}
-  <li>
-    <img src="{{ pathto('_static/cmake-logo-16.png', 1) }}" alt=""
-         style="vertical-align: middle; margin-top: -2px" />
-  </li>
-  <li>
-    <a href="https://cmake.org/">CMake</a>{{ reldelim1 }}
+  <li class="rootlink">
+    <img src="{{ pathto('_static/cmake-logo-16.png', 1) }}" width="16" height="16" alt=""/>
+  {%- if versionswitch is defined %}
+    <a href="https://cmake.org/">CMake</a> <span class="version_switch">{{ release }}</span>
+  {%- else %}
+    <a href="https://cmake.org/">CMake {{ release }}</a>
+  {%- endif %}
+    {{ reldelim1 }}
   </li>
   <li>
-    {%- if versionswitch is defined %}
-    <span class="version_switch">{{ release }}</span>
     <a href="{{ pathto(master_doc) }}">{% trans %}Documentation{% endtrans %}</a>{{ reldelim1 }}
-    {%- else %}
-    <a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>{{ reldelim1 }}
-    {%- endif %}
   </li>
 {% endblock %}
 
diff --git a/Utilities/Sphinx/templates/localtoc.html b/Utilities/Sphinx/templates/localtoc.html
new file mode 100644
index 0000000..0065fe7
--- /dev/null
+++ b/Utilities/Sphinx/templates/localtoc.html
@@ -0,0 +1,8 @@
+{# Sphinx sidebar template: local table of contents.
+   Overridden to remove the "#" link from the "Table of Contents". #}
+{%- if display_toc %}
+  <div>
+    <h3>{{ _('Table of Contents') }}</h3>
+    {{ toc }}
+  </div>
+{%- endif %}
-- 
cgit v0.12


From 3822e95aee92f56328f4bbab561ec9a9c49373b0 Mon Sep 17 00:00:00 2001
From: Nikita Nemkin <nikita@nemkin.ru>
Date: Sun, 2 Feb 2025 13:24:03 +0500
Subject: 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.
---
 Utilities/Sphinx/static/cmake.css      | 209 +++++++++++++++++++++++++++++++++
 Utilities/Sphinx/templates/layout.html |  26 +++-
 2 files changed, 233 insertions(+), 2 deletions(-)

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 @@ code.xref.cmake-guide span.pre {
 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 }} {{ "&mdash;"|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 @@ pageTracker._trackPageview();
 } 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 %}
-- 
cgit v0.12