Merge branch 'migrate-manual-pages-to-hugo'

With this topic branch, there is now a script that pre-renders Git's manual pages as HTML and stores them in `content/`, ready to be committed. This way, no Rails App database is required to hold this content. Signed-off-by: Johannes Schindelin <[email protected]>
git · Nov 21, 2023 · c354750 · c354750
2 parents 603c8a4 + 55c7b5f
commit c354750
Show file tree

Hide file tree

Showing 11 changed files with 371 additions and 112 deletions.
diff --git a/Gemfile b/Gemfile
@@ -6,3 +6,4 @@ gem "octokit"
 gem "rss"
 gem "asciidoctor", "~> 2.0.0"
 gem "nokogiri"
+gem "diffy"
diff --git a/README.md b/README.md
@@ -25,21 +25,23 @@ Note that this will take about 7 times as long, and the site will not be re-rend
 
 ## Update manual pages
 
-(TODO!)
-You can do so using a local Git source clone like this:
+First, install the Ruby prerequisites:
 
-    $ GIT_REPO=../git/.git rake local_index
+	$ bundler install
 
-This will populate the man pages for all Git versions. You can also populate them only for a specific Git version (faster):
+Then, you can build the manual pages using a local Git source clone like this:
+
+    $ ruby ./script/update-docs.rb /path/to/git/.git en
+
+This will populate the manual pages for all Git versions. You can also populate them only for a specific Git version (faster):
 
     $ version=v2.23.0
-    $ GIT_REPO=../git/.git REBUILD_DOC=$version rake local_index
+    $ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
 
 Or you can populate the man pages from GitHub (much slower) like this:
 
     $ export GITHUB_API_TOKEN=github_personal_auth_token
-    $ rake preindex  # all versions
-    $ REBUILD_DOC=$version rake preindex  # specific version
+    $ REBUILD_DOC=$version ruby ./script/update-docs.rb remote en  # specific version
 
 Similarly, you can also populate the localized man pages. From a local clone of https://github.com/jnavila/git-html-l10n :
 

diff --git a/app/views/doc/_versions.html.erb b/app/views/doc/_versions.html.erb
diff --git a/app/models/doc_file.rb → data/lang_names.yml b/app/models/doc_file.rb → data/lang_names.yml
diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
@@ -1,17 +1,21 @@
 <!DOCTYPE html>
 {{ if isset .Params "redirect_to" }}
+{{ $redirect_to := .Params.redirect_to }}
+{{ if not (hasPrefix $redirect_to "https://") }}
+{{ $redirect_to = relURL $redirect_to }}
+{{ end }}
 <html lang="en">
  <head>
   <meta charset="utf-8">
   <title>Redirecting&hellip;</title>
-  <link rel="canonical" href="{{ relURL .Params.redirect_to }}">
-  <meta http-equiv="refresh" content="0; url={{ relURL .Params.redirect_to }}">
+  <link rel="canonical" href="{{ $redirect_to }}">
+  <meta http-equiv="refresh" content="0; url={{ $redirect_to }}">
   <meta name="robots" content="noindex">
  </head>
  <body>
   <script>location="{{ relURL .Params.redirect_to }}"</script>
   <h1>Redirecting&hellip;</h1>
-  <a href="{{ relURL .Params.redirect_to }}">Click here if you are not redirected.</a>
+  <a href="{{ $redirect_to }}">Click here if you are not redirected.</a>
  </body>
 </html>
 {{ else }}
@@ -87,7 +91,7 @@ <h1>Redirecting&hellip;</h1>
               2nd Edition
             </span>
           </div>
-          <div id="main" data-pagefind-filter="category:{{ $section }}" data-pagefind-body class="book edition2">
+          <div id="main" data-pagefind-filter="category:{{ $section }}" data-pagefind-meta="category:Book" data-pagefind-body class="book edition2">
             <h1>{{ .Params.book.section.cs_number }} {{ .Params.book.chapter.title }} - {{ .Params.book.section.title }}</h1>
             <div>
               {{ .Content }}
@@ -98,11 +102,29 @@ <h1>{{ .Params.book.section.cs_number }} {{ .Params.book.chapter.title }} - {{ .
       </div>
       {{ partial "footer.html" . }}
     </div>
+  {{ else if (isset .Params "docname") }}
+    <div class="inner">
+      <div id="content-wrapper">
+        {{ partial "sidebar.html" . }}
+        <div id="content">
+          <div id='reference-version'>
+            {{ partial "ref/versions.html" . }}
+          </div>
+
+          <!-- older manual page versions are less interesting and need to be excluded from the search -->
+          {{ $include_in_search := (or (not (isset .Params "docname")) (isset .Params "latest-changes")) }}
+          <div id="main"{{ if $include_in_search }} data-pagefind-filter="category:{{ $section }}" data-pagefind-meta="category:Reference" data-pagefind-body{{ end }}>
+            {{ safe.HTML (replaceRE "(?s:>NAME</h2>.*?<p)" "$0 data-pagefind-weight=\"7\"" .Content) }}
+          </div>
+        </div>
+      </div>
+      {{ partial "footer.html" . }}
+    </div>
   {{ else }}
     <div class="inner">
       <div id="content-wrapper">
         {{ partial "sidebar.html" . }}
-        <div id="content" data-pagefind-body>
+        <div id="content" data-pagefind-filter="category:{{ $section }}" data-pagefind-body>
           {{ if isset .Params "video_title" }}
 	    <div id="main">
               <h1>{{ .Params.category }} Episode {{ .Params.episode }}</h1>

diff --git a/app/views/doc/_languages.html.erb → layouts/partials/ref/languages.html b/app/views/doc/_languages.html.erb → layouts/partials/ref/languages.html
diff --git a/layouts/partials/ref/versions.html b/layouts/partials/ref/versions.html
@@ -0,0 +1,45 @@
+{% assign versions = site.data.docs.pages[page.docname] %}
+<a class="dropdown-trigger" id="reference-versions-trigger" data-panel-id="previous-versions-dropdown" href="#">
+  {% if page['version'] and page['version'] != versions['latest-changes'] %}
+    Version {{ page['version'] }}
+  {% else %}
+    Latest version
+  {% endif %} ▾ </a>
+<span class="light d-flex">{{ page.docname }} last updated in {{ versions['latest-changes'] }}</span>
+<div class='dropdown-panel left' id='previous-versions-dropdown'>
+  <header>Changes in the <strong>{{ page.docname }}</strong> manual</header>
+  <ol class='reference-previous-versions'>
+    {% for v in versions['page-versions'] %}
+      {% if v.added %}
+        <li>
+        <a href="{{ "/docs/" | append: page.docname | append: "/" | append: v.name | relative_url }}"><span class="version">{{ v.name }}</span>
+          <span class="diff">
+            {% assign range = (1..v.added) %}
+            {% for i in range %}
+              <img src="{{ "/images/icons/green-dot.png" | relative_url }}" />
+            {% endfor %}
+            {% assign range = (1..v.removed) %}
+            {% for i in range %}
+              <img src="{{ "/images/icons/red-dot.png" | relative_url }}" />
+            {% endfor %}
+            {% assign padding = 8 | minus: v.added | minus: v.removed %}
+            {% assign range = (1..padding) %}
+            {% for i in range %}
+              <img src="{{ "/images/icons/grey-dot.png" | relative_url }}" />
+            {% endfor %}
+          </span>
+          <em class="date">{{ site.data.docs.versions[v.name].date }}</em>
+        </a>
+        </li>
+      {% else %}
+        <li class="no-change"><span>{{ v.name }} no changes</span></li>
+      {% endif %}
+    {% endfor %}
+    <li>&nbsp;</li>
+    <!-- <li><a class="more" href="#">See more previous releases →</a></li> -->
+  </ol>
+  <footer>
+    <p>Check your version of git by running</p>
+    <code class="command">git --version</code>
+  </footer>
+</div>
diff --git a/layouts/partials/sidebar.html b/layouts/partials/sidebar.html
@@ -21,7 +21,7 @@
         <a href="{{ relURL "doc" }}"{{ if (eq $section "documentation") }} class="active"{{ end }}>Documentation</a>
         <ul {{ if (eq $section "documentation") }}class="expanded"{{ end }}>
           <li>
-            <a href="{{ relURL "docs" }}"{{ if (eq .Params.Subsection "reference") }} class="active"{{ end }}>Reference</a>
+            <a href="{{ relURL "docs" }}"{{ if or (eq .Params.Subsection "reference") (eq .Params.Subsection "manual") }} class="active"{{ end }}>Reference</a>
           </li>
           <li>
             <a href="{{ relURL "book" }}"{{ if (eq .Params.Subsection "book") }} class="active"{{ end }}>Book</a>