Skip to content

Commit 6442cfb

Browse files
dschodscho
committed
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]>
2 parents 7a5303d + 840cc25 commit 6442cfb

File tree

12 files changed

+442
-120
lines changed

12 files changed

+442
-120
lines changed

‎Gemfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ gem "octokit"
66
gem "rss"
77
gem "asciidoctor", "~> 2.0.0"
88
gem "nokogiri"
9+
gem "diffy"

‎README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -66,21 +66,23 @@ Note that running Pagefind will make the process about 7 times slower, and the s
6666

6767
## Update manual pages
6868

69-
(TODO!)
70-
You can do so using a local Git source clone like this:
69+
First, install the Ruby prerequisites:
7170

72-
$ GIT_REPO=../git/.git rake local_index
71+
$ bundler install
7372

74-
This will populate the man pages for all Git versions. You can also populate them only for a specific Git version (faster):
73+
Then, you can build the manual pages using a local Git source clone like this:
74+
75+
$ ruby ./script/update-docs.rb /path/to/git/.git en
76+
77+
This will populate the manual pages for all Git versions. You can also populate them only for a specific Git version (faster):
7578

7679
$ version=v2.23.0
77-
$ GIT_REPO=../git/.git REBUILD_DOC=$version rake local_index
80+
$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
7881

7982
Or you can populate the man pages from GitHub (much slower) like this:
8083

8184
$ export GITHUB_API_TOKEN=github_personal_auth_token
82-
$ rake preindex # all versions
83-
$ REBUILD_DOC=$version rake preindex # specific version
85+
$ REBUILD_DOC=$version ruby ./script/update-docs.rb remote en # specific version
8486

8587
Similarly, you can also populate the localized man pages. From a local clone of https://github.com/jnavila/git-html-l10n :
8688

@@ -153,6 +155,7 @@ The [list of GUI clients](https://git-scm.com/downloads/guis) has been construct
153155

154156
* https://gohugo.io/
155157
* https://gohugo.io/content-management/shortcodes/
158+
* https://github.com/google/re2/wiki/Syntax/ (for Hugo's regular expression syntax)
156159

157160
### Pagefind (client-side search)
158161

‎app/views/doc/_versions.html.erb‎

Lines changed: 0 additions & 40 deletions
This file was deleted.

‎assets/js/application.js‎

Lines changed: 58 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,19 @@ var Search = {
189189
</ul>
190190
</td>
191191
</tr>
192-
<tr>
192+
<tr style="display:none">
193+
<td class="category">Reference</td>
194+
<td class="matches">
195+
<ul id="ul-reference"></ul>
196+
</td>
197+
</tr>
198+
<tr style="display:none">
199+
<td class="category">Book</td>
200+
<td class="matches">
201+
<ul id="ul-book"></ul>
202+
</td>
203+
</tr>
204+
<tr id="row-any">
193205
<td class="category"> &nbsp; </td>
194206
<td class="matches">
195207
<ul>
@@ -217,22 +229,46 @@ var Search = {
217229
}`);
218230
loadButton.loading = false;
219231

232+
const ulReference = $("#ul-reference")
233+
const ulBook = $("#ul-book")
234+
220235
const chunkLength = 10;
221236
let displayCount = 0;
237+
238+
const categorizeResult = (i) => {
239+
while (i < displayCount && typeof results.results[i].data === 'object') {
240+
const result = results.results[i++];
241+
if (result.data.meta.category === 'Reference') {
242+
if (ulReference.children().length === 0) ulReference.parent().parent().css("display", "table-row")
243+
ulReference.append(result.li)
244+
} else if (result.data.meta.category === 'Book') {
245+
if (ulBook.children().length === 0) ulBook.parent().parent().css("display", "table-row")
246+
ulBook.append(result.li)
247+
}
248+
}
249+
};
250+
222251
const loadResultsChunk = () => {
223252
if (loadButton.loading || displayCount >= results.results.length) return;
224253

225254
loadButton.loading = true;
226255
const n = displayCount + chunkLength;
227256
while (displayCount < n) {
228-
const li = $("<li><a>&hellip;</a></li>");
229-
li.insertBefore(loadButton);
257+
const result = results.results[displayCount]
258+
result.li = $("<li><a>&hellip;</a></li>");
259+
result.li.insertBefore(loadButton);
230260

231261
// load the result lazily
232-
(async () => {
233-
const result = await results.results[displayCount].data();
234-
li.html(`<a href = "${result.url}">${result.meta.title}</a>`);
235-
})().catch(console.log);
262+
(async (i) => {
263+
result.data = await results.results[displayCount].data();
264+
if (!i || typeof results.results[i - 1].data === 'object') categorizeResult(i);
265+
result.data.meta.title = result.data.meta.title.replace(/^Git - (.*) Documentation$/, "$1")
266+
result.data.url = result.data.url.replace(/\.html$/, '')
267+
result.li.html(`<a href = "${result.data.url}">${result.data.meta.title}</a>`);
268+
})(displayCount).catch((err) => {
269+
console.log(err);
270+
result.li.html(`<i>Error loading result</i>`);
271+
});
236272

237273
if (++displayCount >= results.results.length) {
238274
loadButton.remove();
@@ -303,7 +339,14 @@ var Search = {
303339
}
304340
(async () => {
305341
Search.pagefind = await import(`${baseURLPrefix}pagefind/pagefind.js`);
306-
const options = {}
342+
const options = {
343+
ranking: {
344+
pageLength: 0.1, // boost longer pages
345+
termFrequency: 0.1, // do not favor short pages
346+
termSaturation: 2, // look for pages with more matches
347+
termSimilarity: 9, // prefer exact matches
348+
}
349+
}
307350
const language = this.getQueryValue('language');
308351
if (language) options.language = language;
309352
await Search.pagefind.options(options);
@@ -322,9 +365,15 @@ var Search = {
322365
showSubResults: true,
323366
showImages: false,
324367
language,
368+
ranking: {
369+
pageLength: 0.1, // boost longer pages
370+
termFrequency: 0.1, // do not favor short pages
371+
termSaturation: 2, // look for pages with more matches
372+
termSimilarity: 9, // prefer exact matches
373+
},
325374
processResult: function (result) {
326375
result.url = result.url.replace(/\.html$/, "")
327-
return result
376+
return result
328377
},
329378
});
330379

app/models/doc_file.rb renamed to data/lang_names.yml

File renamed without changes.

‎hugo.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ module:
2626
target: content/book
2727
- source: external/book/static/book
2828
target: static/book
29+
- source: external/docs/data
30+
target: data
31+
- source: external/docs/content
32+
target: content
2933
params:
3034
hugo_version: 0.134.3
3135
pagefind_version: 1.1.1

‎layouts/_default/baseof.html‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,21 @@
11
<!DOCTYPE html>
22
{{ if isset .Params "redirect_to" }}
3+
{{ $redirect_to := .Params.redirect_to }}
4+
{{ if not (hasPrefix $redirect_to "https://") }}
5+
{{ $redirect_to = relURL $redirect_to }}
6+
{{ end }}
37
<html lang="en">
48
<head>
59
<meta charset="utf-8">
610
<title>Redirecting&hellip;</title>
7-
<link rel="canonical" href="{{ relURL .Params.redirect_to }}">
8-
<meta http-equiv="refresh" content="0; url={{ relURL .Params.redirect_to }}">
11+
<link rel="canonical" href="{{ $redirect_to }}">
12+
<meta http-equiv="refresh" content="0; url={{ $redirect_to }}">
913
<meta name="robots" content="noindex">
1014
</head>
1115
<body>
1216
<script>location="{{ relURL .Params.redirect_to }}"</script>
1317
<h1>Redirecting&hellip;</h1>
14-
<a href="{{ relURL .Params.redirect_to }}">Click here if you are not redirected.</a>
18+
<a href="{{ $redirect_to }}">Click here if you are not redirected.</a>
1519
</body>
1620
</html>
1721
{{ else }}
@@ -88,7 +92,7 @@ <h1>Redirecting&hellip;</h1>
8892
2nd Edition
8993
</span>
9094
</div>
91-
<div id="main" data-pagefind-filter="category:book" data-pagefind-body class="book edition2">
95+
<div id="main" data-pagefind-filter="category:book" data-pagefind-meta="category:Book" data-pagefind-weight="0.05" data-pagefind-body class="book edition2">
9296
<h1>{{ .Params.book.section.cs_number }} {{ .Params.book.chapter.title }} - {{ .Params.book.section.title }}</h1>
9397
<div>
9498
{{ .Content }}
@@ -99,11 +103,36 @@ <h1>{{ .Params.book.section.cs_number }} {{ .Params.book.chapter.title }} - {{ .
99103
</div>
100104
{{ partial "footer.html" . }}
101105
</div>
106+
{{ else if (isset .Params "docname") }}
107+
<div class="inner">
108+
<div id="content-wrapper">
109+
{{ partial "sidebar.html" . }}
110+
<div id="content">
111+
<div id='reference-version'>
112+
{{ partial "ref/versions.html" . }}
113+
</div>
114+
115+
<!-- older manual page versions are less interesting and need to be excluded from the search -->
116+
{{ $include_in_search := (or (not (isset .Params "docname")) (isset .Params "latest-changes") (isset .Params "lang")) }}
117+
<div id="main"{{ if $include_in_search }} data-pagefind-filter="category:reference" data-pagefind-meta="category:Reference" data-pagefind-weight="0.05" data-pagefind-body{{ end }}>
118+
{{ .Content }}
119+
{{ $match := findRESubmatch "(?s)>NAME</h2>.*?<p[^>]*>(git-)?([^ ]+)" .Content 1 }}
120+
{{ if (eq ($match | len) 1) }}
121+
{{ $command_name := (index (index $match 0) 2) }}
122+
{{ $weight := cond (strings.Contains $command_name "-") 7 10 }}
123+
<!-- boost the command name in the search -->
124+
<h3 hidden="true" data-pagefind-weight="{{ $weight }}">{{ $command_name }}</h3>
125+
{{ end }}
126+
</div>
127+
</div>
128+
</div>
129+
{{ partial "footer.html" . }}
130+
</div>
102131
{{ else }}
103132
<div class="inner">
104133
<div id="content-wrapper">
105134
{{ partial "sidebar.html" . }}
106-
<div id="content" data-pagefind-body>
135+
<div id="content" data-pagefind-filter="category:{{ $section }}" data-pagefind-weight="0.05" data-pagefind-body>
107136
{{ if (eq .Page.Path "/docs") }}
108137
{{ partial "ref/index.html" . }}
109138
{{ else if isset .Params "video_title" }}

app/views/doc/_languages.html.erb renamed to layouts/partials/ref/languages.html

File renamed without changes.

‎layouts/partials/ref/versions.html‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{% assign versions = site.data.docs.pages[page.docname] %}
2+
<a class="dropdown-trigger" id="reference-versions-trigger" data-panel-id="previous-versions-dropdown" href="#">
3+
{% if page['version'] and page['version'] != versions['latest-changes'] %}
4+
Version {{ page['version'] }}
5+
{% else %}
6+
Latest version
7+
{% endif %} ▾ </a>
8+
<span class="light d-flex">{{ page.docname }} last updated in {{ versions['latest-changes'] }}</span>
9+
<div class='dropdown-panel left' id='previous-versions-dropdown'>
10+
<header>Changes in the <strong>{{ page.docname }}</strong> manual</header>
11+
<ol class='reference-previous-versions'>
12+
{% for v in versions['page-versions'] %}
13+
{% if v.added %}
14+
<li>
15+
<a href="{{ "/docs/" | append: page.docname | append: "/" | append: v.name | relative_url }}"><span class="version">{{ v.name }}</span>
16+
<span class="diff">
17+
{% assign range = (1..v.added) %}
18+
{% for i in range %}
19+
<img src="{{ "/images/icons/green-dot.png" | relative_url }}" />
20+
{% endfor %}
21+
{% assign range = (1..v.removed) %}
22+
{% for i in range %}
23+
<img src="{{ "/images/icons/red-dot.png" | relative_url }}" />
24+
{% endfor %}
25+
{% assign padding = 8 | minus: v.added | minus: v.removed %}
26+
{% assign range = (1..padding) %}
27+
{% for i in range %}
28+
<img src="{{ "/images/icons/grey-dot.png" | relative_url }}" />
29+
{% endfor %}
30+
</span>
31+
<em class="date">{{ site.data.docs.versions[v.name].date }}</em>
32+
</a>
33+
</li>
34+
{% else %}
35+
<li class="no-change"><span>{{ v.name }} no changes</span></li>
36+
{% endif %}
37+
{% endfor %}
38+
<li>&nbsp;</li>
39+
<!-- <li><a class="more" href="#">See more previous releases →</a></li> -->
40+
</ol>
41+
<footer>
42+
<p>Check your version of git by running</p>
43+
<code class="command">git --version</code>
44+
</footer>
45+
</div>

‎layouts/partials/sidebar.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
<a href="{{ relURL "doc" }}"{{ if (eq $section "documentation") }} class="active"{{ end }}>Documentation</a>
2222
<ul {{ if (eq $section "documentation") }}class="expanded"{{ end }}>
2323
<li>
24-
<a href="{{ relURL "docs" }}"{{ if (eq .Params.Subsection "reference") }} class="active"{{ end }}>Reference</a>
24+
<a href="{{ relURL "docs" }}"{{ if or (eq .Params.Subsection "reference") (eq .Params.Subsection "manual") }} class="active"{{ end }}>Reference</a>
2525
</li>
2626
<li>
2727
<a href="{{ relURL "book" }}"{{ if (eq .Params.Subsection "book") }} class="active"{{ end }}>Book</a>

0 commit comments

Comments
 (0)