Skip to content

Commit 3fbfce1

Browse files
nik9000nik9000
authored
Skip post-book actions if we can (#673)
Skips some of the actions that we take after building all branches of a book if we can get away with skipping them and reworks some of the logging. This should marginally speed up the `--all` build and and make it *much* easier to spot which books are rebuilt in which build by suppressing a lot of the logging noise.
1 parent 99caf9e commit 3fbfce1

File tree

4 files changed

+199
-42
lines changed

4 files changed

+199
-42
lines changed

‎build_docs.pl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,7 @@ sub build_all {
231231
say "Skipping documentation builds."
232232
}
233233
else {
234+
say "Building docs";
234235
build_entries( $build_dir, $temp_dir, $toc, @$contents );
235236

236237
say "Writing main TOC";

‎integtest/Makefile

Lines changed: 110 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ check: \
2525
keep_hash \
2626
sub_dir \
2727
keep_hash_and_sub_dir \
28+
multi_branch \
2829
open_all
2930

3031
.PHONY: style
@@ -170,6 +171,7 @@ keep_hash:
170171
--target_repo $(TMP)/dest.git \
171172
--conf $(TMP)/conf.yaml \
172173
--keep_hash | tee $(TMP)/out
174+
$(call GREP_V,'Test book',$(TMP)/out)
173175
$(call GREP,'No changes to push',$(TMP)/out)
174176

175177
# We expact the same files as the minimal because we the changes that we
@@ -196,8 +198,10 @@ sub_dir:
196198
/docs_build/build_docs.pl --in_standard_docker --all --push \
197199
--target_repo $(TMP)/dest.git \
198200
--conf $(TMP)/conf.yaml \
199-
--sub_dir source:master:$(TMP)/to_sub
200-
201+
--sub_dir source:master:$(TMP)/to_sub | tee $(TMP)/out
202+
$(call GREP,'Test book: Building master...',$(TMP)/out)
203+
$(call GREP,'Test book: Finished master',$(TMP)/out)
204+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
201205
$(call MINIMAL_ALL_EXPECTED_FILES,'local changes')
202206

203207
.PHONY: keep_hash_and_sub_dir
@@ -214,7 +218,11 @@ keep_hash_and_sub_dir:
214218
sed 's|--tmp--|$(TMP)|' two_repos_conf.yaml > $(TMP)/conf.yaml
215219
/docs_build/build_docs.pl --in_standard_docker --all --push \
216220
--target_repo $(TMP)/dest.git \
217-
--conf $(TMP)/conf.yaml
221+
--conf $(TMP)/conf.yaml | tee $(TMP)/out
222+
$(call GREP,'Test book: Building master...',$(TMP)/out)
223+
$(call GREP,'Test book: Finished master',$(TMP)/out)
224+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
225+
$(call GREP,'Pushing changes',$(TMP)/out)
218226

219227
# Move a "bad" file into source2 so we can be sure we're not picking it up
220228
cp ../README.asciidoc $(TMP)/source2/index.asciidoc
@@ -225,8 +233,9 @@ keep_hash_and_sub_dir:
225233
/docs_build/build_docs.pl --in_standard_docker --all --push \
226234
--target_repo $(TMP)/dest.git \
227235
--conf $(TMP)/conf.yaml \
228-
--keep_hash | tee /tmp/out
229-
$(call GREP,'No changes to push',/tmp/out)
236+
--keep_hash | tee $(TMP)/out
237+
$(call GREP_V,'Test book',$(TMP)/out)
238+
$(call GREP,'No changes to push',$(TMP)/out)
230239

231240
# Setup the directory we'd like to substitute
232241
mkdir -p $(TMP)/to_sub/docs
@@ -237,11 +246,84 @@ keep_hash_and_sub_dir:
237246
--target_repo $(TMP)/dest.git \
238247
--conf $(TMP)/conf.yaml \
239248
--keep_hash --sub_dir source1:master:$(TMP)/to_sub | tee $(TMP)/out
249+
$(call GREP,'Test book: Building master...',$(TMP)/out)
250+
$(call GREP,'Test book: Finished master',$(TMP)/out)
251+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
240252
$(call GREP,'Pushing changes',$(TMP)/out)
241253

242254
git clone $(TMP)/dest.git $(TMP)/dest
243255
$(call GREP,'extra extra extra',$(TMP)/dest/html/test/current/_chapter.html)
244256

257+
.PHONY: multi_branch
258+
multi_branch:
259+
# Tests for how we rebuild books with multiple branches
260+
261+
# When the book hasn't been built before we build all branches
262+
rm -rf $(TMP)
263+
$(call INIT_REPO_WITH_FILE,$(TMP)/source,minimal.asciidoc,docs/index.asciidoc)
264+
cd $(TMP)/source && git checkout -b prev
265+
git init --bare $(TMP)/dest.git
266+
267+
sed 's|--tmp--|$(TMP)|' multi_branch.yaml > $(TMP)/conf.yaml
268+
/docs_build/build_docs.pl --in_standard_docker --all --push \
269+
--target_repo $(TMP)/dest.git \
270+
--conf $(TMP)/conf.yaml | tee $(TMP)/out
271+
$(call GREP,'Test book: Building master...',$(TMP)/out)
272+
$(call GREP,'Test book: Finished master',$(TMP)/out)
273+
$(call GREP,'Test book: Building prev...',$(TMP)/out)
274+
$(call GREP,'Test book: Finished prev',$(TMP)/out)
275+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
276+
$(call GREP,'Test book: Writing versions TOC',$(TMP)/out)
277+
$(call GREP,'Pushing changes',$(TMP)/out)
278+
279+
git clone $(TMP)/dest.git $(TMP)/dest
280+
# The main index links to the current version
281+
$(call GREP,'<a class="ulink" href="test/current/index.html" target="_top">Test book \[master\]</a>',$(TMP)/dest/html/index.html)
282+
$(call GREP,'<a class="ulink" href="test/index.html" target="_top">other versions</a>',$(TMP)/dest/html/index.html)
283+
# And the book's index links to all versions
284+
$(call GREP,'<a class="ulink" href="current/index.html" target="_top">Test book: master (current)</a>',$(TMP)/dest/html/test/index.html)
285+
$(call GREP,'<a class="ulink" href="prev/index.html" target="_top">Test book: prev</a>',$(TMP)/dest/html/test/index.html)
286+
# And all versions have been built
287+
[ -s $(TMP)/dest/html/test/current/index.html ]
288+
[ -s $(TMP)/dest/html/test/master/index.html ]
289+
[ -s $(TMP)/dest/html/test/prev/index.html ]
290+
291+
# When one of the non-current branches has changed we rebuild it but do not
292+
# copy the current branch
293+
cd $(TMP)/source && \
294+
git checkout prev && \
295+
echo "changed" >> docs/index.asciidoc && \
296+
git add . && \
297+
git commit -m "change"
298+
/docs_build/build_docs.pl --in_standard_docker --all --push \
299+
--target_repo $(TMP)/dest.git \
300+
--conf $(TMP)/conf.yaml | tee $(TMP)/out
301+
$(call GREP_V,'Test book: Building master...',$(TMP)/out)
302+
$(call GREP_V,'Test book: Finished master',$(TMP)/out)
303+
$(call GREP,'Test book: Building prev...',$(TMP)/out)
304+
$(call GREP,'Test book: Finished prev',$(TMP)/out)
305+
$(call GREP_V,'Test book: Copying master to current',$(TMP)/out)
306+
$(call GREP,'Test book: Writing versions TOC',$(TMP)/out)
307+
$(call GREP,'Pushing changes',$(TMP)/out)
308+
309+
# When the current branch has changed we rebuild it and copy it to the
310+
# current branch
311+
cd $(TMP)/source && \
312+
git checkout master && \
313+
echo "changed" >> docs/index.asciidoc && \
314+
git add . && \
315+
git commit -m "change"
316+
/docs_build/build_docs.pl --in_standard_docker --all --push \
317+
--target_repo $(TMP)/dest.git \
318+
--conf $(TMP)/conf.yaml | tee $(TMP)/out
319+
$(call GREP,'Test book: Building master...',$(TMP)/out)
320+
$(call GREP,'Test book: Finished master',$(TMP)/out)
321+
$(call GREP_V,'Test book: Building prev...',$(TMP)/out)
322+
$(call GREP_V,'Test book: Finished prev',$(TMP)/out)
323+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
324+
$(call GREP,'Test book: Writing versions TOC',$(TMP)/out)
325+
$(call GREP,'Pushing changes',$(TMP)/out)
326+
245327
.PHONY: open_all
246328
open_all:
247329
# Test that `--all --open` starts nginx in a usable way.
@@ -259,21 +341,6 @@ open_all:
259341
$(call GREP,'Location: http://localhost:8000/guide/en/elasticsearch/reference/current/setup.html',$(TMP)/guide/rdir)
260342
kill -QUIT $$(cat /run/nginx/nginx.pid)
261343

262-
define GREP=
263-
# grep for a string in a file, outputting the whole file if there isn't
264-
# a match.
265-
[ -e $(2) ] || { \
266-
echo "can't find $(2)"; \
267-
ls $$(dirname $(2)); \
268-
false; \
269-
}
270-
grep $(1) $(2) > /dev/null || { \
271-
echo "Couldn't find $(1) in $(2):"; \
272-
cat $(2); \
273-
false; \
274-
}
275-
endef
276-
277344
define SETUP_MINIMAL_ALL=
278345
# First build a repository to use as the source.
279346
$(call INIT_REPO_WITH_FILE,$(TMP)/source,minimal.asciidoc,index.asciidoc)
@@ -292,7 +359,11 @@ define BUILD_MINIMAL_ALL=
292359
$(SETUP_MINIMAL_ALL)
293360
/docs_build/build_docs.pl --in_standard_docker --all --push \
294361
--target_repo $(TMP)/dest.git \
295-
--conf $(TMP)/conf.yaml
362+
--conf $(TMP)/conf.yaml | tee $(TMP)/out
363+
$(call GREP,'Test book: Building master...',$(TMP)/out)
364+
$(call GREP,'Test book: Finished master',$(TMP)/out)
365+
$(call GREP,'Test book: Copying master to current',$(TMP)/out)
366+
$(call GREP,'Test book: Writing redirect to current branch...',$(TMP)/out)
296367
endef
297368

298369
define MINIMAL_ALL_EXPECTED_FILES=
@@ -323,13 +394,28 @@ define GREP=
323394
# grep for a string in a file, outputting the whole file if there isn't
324395
# a match.
325396
[ -e $(2) ] || { \
326-
echo "can't find $(2)"; \
397+
echo "can't find \'$(2)\'"; \
327398
ls $$(dirname $(2)); \
328399
false; \
329400
}
330-
grep $(1) $(2) > /dev/null || { \
331-
echo "Couldn't" find $(1) in $(2):; \
401+
grep -q $(1) $(2) || { \
402+
echo "Couldn't" find \'$(1)\' in \'$(2)\':; \
332403
cat $(2); \
333404
false; \
334405
}
335406
endef
407+
408+
define GREP_V=
409+
# grep for a string in a file, outputting the whole file if there *is*
410+
# a match.
411+
[ -e $(2) ] || { \
412+
echo "can't find \'$(2)\'"; \
413+
ls $$(dirname $(2)); \
414+
false; \
415+
}
416+
grep -qv $(1) $(2) || { \
417+
echo Found \'$(1)\' in \'$(2)\':; \
418+
cat $(2); \
419+
false; \
420+
}
421+
endef

‎integtest/multi_branch.yaml

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# This is a small config file for build_docs.pl used for testing
2+
3+
# This block is required even when building a single doc
4+
template:
5+
path: .template/
6+
branch:
7+
default:
8+
base_url: 'https://www.elastic.co/'
9+
template_url: 'https://www.elastic.co/guide_template'
10+
staging:
11+
base_url: 'https://stag-www.elastic.co/'
12+
template_url: 'https://stag-www.elastic.co/guide_template'
13+
defaults:
14+
POSTHEAD: |
15+
<link rel="stylesheet" type="text/css" href="styles.css" />
16+
FINAL: |
17+
<script type="text/javascript" src="docs.js"></script>
18+
<script type='text/javascript' src='https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js?lang=yaml'></script>
19+
20+
paths:
21+
# These two configure where to put things in the --target_repo. The
22+
# paths are resolved relative to the root of the --target_repo.
23+
build: html/
24+
branch_tracker: html/branches.yaml
25+
# This configures which directory to use for cloning repos. Because
26+
# these are big we tend to want them to be in a non-temporary but
27+
# .gitignored spot. The path is resolved relative to the root of the
28+
# docs repo.
29+
repos: --tmp--/repos/
30+
31+
# This configures all of the repositories used to build the docs
32+
repos:
33+
# Normally we use the `https://` prefix to clone from github but this file
34+
# is for testing so use a string that we can find with sed and replace with
35+
# a file.
36+
source: --tmp--/source
37+
38+
# The title to use for the table of contents
39+
contents_title: Elastic Stack and Product Documentation
40+
41+
# The actual books to build
42+
contents:
43+
-
44+
title: Test book
45+
prefix: test
46+
current: master
47+
branches: [ master, prev ]
48+
index: docs/index.asciidoc
49+
tags: test tag
50+
subject: Test
51+
sources:
52+
-
53+
repo: source
54+
path: docs/index.asciidoc

0 commit comments

Comments
 (0)