1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
"""Wrappers for website documentation."""
load("//tools:defs.bzl", "short_path")
# DocInfo is a provider which simple adds sufficient metadata to the source
# files (and additional data files) so that a jeyll header can be constructed
# dynamically. This is done the via BUILD system so that the plain
# documentation files can be viewable without non-compliant markdown headers.
DocInfo = provider(
"Encapsulates information for a documentation page.",
fields = [
"layout",
"description",
"permalink",
"category",
"subcategory",
"weight",
"editpath",
"authors",
"include_in_menu",
],
)
def _doc_impl(ctx):
return [
DefaultInfo(
files = depset(ctx.files.src + ctx.files.data),
),
DocInfo(
layout = ctx.attr.layout,
description = ctx.attr.description,
permalink = ctx.attr.permalink,
category = ctx.attr.category,
subcategory = ctx.attr.subcategory,
weight = ctx.attr.weight,
editpath = short_path(ctx.files.src[0].short_path),
authors = ctx.attr.authors,
include_in_menu = ctx.attr.include_in_menu,
),
]
doc = rule(
implementation = _doc_impl,
doc = "Annotate a document for jekyll headers.",
attrs = {
"src": attr.label(
doc = "The markdown source file.",
mandatory = True,
allow_single_file = True,
),
"data": attr.label_list(
doc = "Additional data files (e.g. images).",
allow_files = True,
),
"layout": attr.string(
doc = "The document layout.",
default = "docs",
),
"description": attr.string(
doc = "The document description.",
default = "",
),
"permalink": attr.string(
doc = "The document permalink.",
mandatory = True,
),
"category": attr.string(
doc = "The document category.",
default = "",
),
"subcategory": attr.string(
doc = "The document subcategory.",
default = "",
),
"weight": attr.string(
doc = "The document weight.",
default = "50",
),
"authors": attr.string_list(),
"include_in_menu": attr.bool(
doc = "Include document in the navigation menu.",
default = True,
),
},
)
def _docs_impl(ctx):
# Tarball is the actual output.
tarball = ctx.actions.declare_file(ctx.label.name + ".tgz")
# But we need an intermediate builder to translate the files.
builder = ctx.actions.declare_file("%s-builder" % ctx.label.name)
builder_content = [
"#!/bin/bash",
"set -euo pipefail",
"declare -r T=$(mktemp -d)",
"function cleanup {",
" rm -rf $T",
"}",
"trap cleanup EXIT",
]
for dep in ctx.attr.deps:
doc = dep[DocInfo]
# Sanity check the permalink.
if not doc.permalink.endswith("/"):
fail("permalink %s for target %s should end with /" % (
doc.permalink,
ctx.label.name,
))
# Construct the header.
header = """\
description: {description}
permalink: {permalink}
category: {category}
subcategory: {subcategory}
weight: {weight}
editpath: {editpath}
authors: {authors}
layout: {layout}
include_in_menu: {include_in_menu}"""
for f in dep.files.to_list():
# Is this a markdown file? If not, then we ensure that it ends up
# in the same path as the permalink for relative addressing.
if not f.basename.endswith(".md"):
builder_content.append("mkdir -p $T/%s" % doc.permalink)
builder_content.append("cp %s $T/%s" % (f.path, doc.permalink))
continue
# Is this a post? If yes, then we must put this in the _posts
# directory. This directory is treated specially with respect to
# pagination and page generation.
dest = f.short_path
if doc.layout == "post":
dest = "_posts/" + f.basename
builder_content.append("echo Processing %s... >&2" % f.short_path)
builder_content.append("mkdir -p $T/$(dirname %s)" % dest)
# Construct the header dynamically. We include the title field from
# the markdown itself, as this is the g3doc format required. The
# title will be injected by the web layout however, so we don't
# want this to appear in the document.
args = dict([(k, getattr(doc, k)) for k in dir(doc)])
builder_content.append("title=\"$(grep -E '^# ' %s | head -n 1 | cut -d'#' -f2- || true)\"" % f.path)
builder_content.append("cat >$T/%s <<EOF" % dest)
builder_content.append("---")
builder_content.append("title: $title")
builder_content.append(header.format(**args))
builder_content.append("---")
builder_content.append("EOF")
# To generate the final page, we need to strip out the title (which
# was pulled above to generate the annotation in the frontmatter,
# and substitute the [TOC] tag with the {% toc %} plugin tag. Note
# that the pipeline here is almost important, as the grep will
# return non-zero if the file is empty, but we ignore that within
# the pipeline.
builder_content.append("grep -v -E '^# ' %s | sed -e 's|^\\[TOC\\]$|- TOC\\n{:toc}|' >>$T/%s" %
(f.path, dest))
builder_content.append("declare -r filename=$(readlink -m %s)" % tarball.path)
builder_content.append("(cd $T && tar -zcf \"${filename}\" .)\n")
ctx.actions.write(builder, "\n".join(builder_content), is_executable = True)
# Generate the tarball.
ctx.actions.run(
inputs = depset(ctx.files.deps),
outputs = [tarball],
progress_message = "Generating %s" % ctx.label,
executable = builder,
)
return [DefaultInfo(
files = depset([tarball]),
)]
docs = rule(
implementation = _docs_impl,
doc = "Construct a site tarball from doc dependencies.",
attrs = {
"deps": attr.label_list(
doc = "All document dependencies.",
),
},
)
|
