Google Git
Sign in
bazel / bazel / fc66ead4d499e2933885747452e6af908196a059 / . / src / main / java / com / google / devtools / build / docgen / DocgenConsts.java
blob: 825f87500d6eef598ea121d1a1d714f7df7ec0ba [file] [log] [blame]
Damien Martin-Guillerezf88f4d82015-09-25 13:56:55 +0000[diff] [blame]1// Copyright 2014 The Bazel Authors. All rights reserved.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14package com.google.devtools.build.docgen;
15
Laszlo Csomor5a4f2862015-02-26 12:47:14 +0000[diff] [blame]16import com.google.common.base.Joiner;
17import com.google.common.collect.ImmutableList;
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]18import com.google.common.collect.ImmutableMap;
19import com.google.devtools.build.lib.util.FileType;
20import com.google.devtools.build.lib.util.FileTypeSet;
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]21import java.util.regex.Pattern;
22
23/**
24 * All the constants for the Docgen project.
25 */
26public class DocgenConsts {
27
28 public static final String LS = "\n";
29
David Chen915dbdf2016-08-29 10:25:17 +0000[diff] [blame]30 public static final String BE_TEMPLATE_DIR =
31 "com/google/devtools/build/docgen/templates/be";
32 public static final String SINGLE_BE_TEMPLATE = BE_TEMPLATE_DIR + "/single-page.vm";
David Chene1bd5da2015-10-22 21:40:31 +0000[diff] [blame]33 public static final String COMMON_DEFINITIONS_TEMPLATE =
David Chen915dbdf2016-08-29 10:25:17 +0000[diff] [blame]34 BE_TEMPLATE_DIR + "/common-definitions.vm";
35 public static final String OVERVIEW_TEMPLATE = BE_TEMPLATE_DIR + "/overview.vm";
36 public static final String RULES_TEMPLATE = BE_TEMPLATE_DIR + "/rules.vm";
37 public static final String BE_NAV_TEMPLATE = BE_TEMPLATE_DIR + "/be-nav.vm";
fwe9dea9e82022-03-21 09:37:07 -0700[diff] [blame]38 public static final String BE_TOC_TEMPLATE = BE_TEMPLATE_DIR + "/be-toc.vm";
David Chen24f2d992015-08-17 17:25:46 +0000[diff] [blame]39
gregce773b95f2020-05-19 09:51:09 -0700[diff] [blame]40 public static final String STARLARK_LIBRARY_TEMPLATE =
fwee5981b72022-02-28 07:38:06 -0800[diff] [blame]41 "com/google/devtools/build/docgen/templates/starlark-library.vm";
gregce773b95f2020-05-19 09:51:09 -0700[diff] [blame]42 public static final String STARLARK_NAV_TEMPLATE =
fwee5981b72022-02-28 07:38:06 -0800[diff] [blame]43 "com/google/devtools/build/docgen/templates/starlark-nav.vm";
gregce773b95f2020-05-19 09:51:09 -0700[diff] [blame]44 public static final String STARLARK_MODULE_CATEGORY_TEMPLATE =
fwee5981b72022-02-28 07:38:06 -0800[diff] [blame]45 "com/google/devtools/build/docgen/templates/starlark-category.vm";
gregce773b95f2020-05-19 09:51:09 -0700[diff] [blame]46 public static final String STARLARK_OVERVIEW_TEMPLATE =
fwee5981b72022-02-28 07:38:06 -0800[diff] [blame]47 "com/google/devtools/build/docgen/templates/starlark-overview.vm";
fwe9dea9e82022-03-21 09:37:07 -0700[diff] [blame]48 public static final String STARLARK_TOC_TEMPLATE =
49 "com/google/devtools/build/docgen/templates/starlark-toc.vm";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]50
51 public static final String VAR_LEFT_PANEL = "LEFT_PANEL";
52
53 public static final String VAR_SECTION_BINARY = "SECTION_BINARY";
54 public static final String VAR_SECTION_LIBRARY = "SECTION_LIBRARY";
55 public static final String VAR_SECTION_TEST = "SECTION_TEST";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]56 public static final String VAR_SECTION_OTHER = "SECTION_OTHER";
57
58 public static final String VAR_IMPLICIT_OUTPUTS = "IMPLICIT_OUTPUTS";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]59 public static final String VAR_NAME = "NAME";
David Chen937a3d62015-06-19 09:17:36 +0000[diff] [blame]60 public static final String VAR_LANG_SPECIFIC_HEADER_TABLE = "LANG_SPECIFIC_HEADER_TABLE";
61 public static final String VAR_OTHER_RULES_HEADER_TABLE = "OTHER_RULES_HEADER_TABLE";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]62 public static final String VAR_COMMON_ATTRIBUTE_DEFINITION = "COMMON_ATTRIBUTE_DEFINITION";
63 public static final String VAR_TEST_ATTRIBUTE_DEFINITION = "TEST_ATTRIBUTE_DEFINITION";
64 public static final String VAR_BINARY_ATTRIBUTE_DEFINITION = "BINARY_ATTRIBUTE_DEFINITION";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]65
gregce773b95f2020-05-19 09:51:09 -0700[diff] [blame]66 public static final String VAR_SECTION_STARLARK_BUILTIN = "SECTION_BUILTIN";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]67
Googlerdac0d402021-01-13 06:56:57 -0800[diff] [blame]68 public static final String TYPICAL_ATTRIBUTES = "typical";
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]69 public static final String COMMON_ATTRIBUTES = "common";
70 public static final String TEST_ATTRIBUTES = "test";
71 public static final String BINARY_ATTRIBUTES = "binary";
72
73 /**
74 * Mark the attribute as deprecated in the Build Encyclopedia.
75 */
76 public static final String FLAG_DEPRECATED = "DEPRECATED";
77 public static final String FLAG_GENERIC_RULE = "GENERIC_RULE";
78
Laszlo Csomor5a4f2862015-02-26 12:47:14 +0000[diff] [blame]79 public static final String HEADER_COMMENT = Joiner.on("\n").join(ImmutableList.<String>of(
Laszlo Csomor5a4f2862015-02-26 12:47:14 +0000[diff] [blame]80 "<!DOCTYPE html>",
81 "<!--",
Dan Fabulich1d35ca02018-07-05 16:08:06 -0700[diff] [blame]82 " This document is synchronized with Bazel releases.",
83 " To edit, submit changes to the Bazel source code.",
Laszlo Csomor5a4f2862015-02-26 12:47:14 +0000[diff] [blame]84 "-->",
85 "",
David Chenc23d6612015-11-02 22:56:13 +0000[diff] [blame]86 "<!-- Generated by //java/com/google/devtools/build/docgen:build-encyclopedia.zip -->"));
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]87
88 public static final FileTypeSet JAVA_SOURCE_FILE_SUFFIX = FileTypeSet.of(FileType.of(".java"));
89
90 public static final String META_KEY_NAME = "NAME";
91 public static final String META_KEY_TYPE = "TYPE";
92 public static final String META_KEY_FAMILY = "FAMILY";
93
94 /**
95 * Types a rule can have (Binary, Library, Test or Other).
96 */
97 public static enum RuleType {
98 BINARY, LIBRARY, TEST, OTHER
99 }
100
101 /**
David Chenac13e222016-02-24 22:17:42 +0000[diff] [blame]102 * Reference to another rule or Build Encyclopedia section.
103 *
104 * <p>The format of a link reference is rule.attribute (e.g. cc_library.deps). In the case of
105 * static pages such as common definitions the format is page.heading
106 * (e.g. common-definitions.label-expansion).
107 */
108 public static final Pattern BLAZE_RULE_LINK = Pattern.compile(
David Chenb0d20462016-03-01 01:17:26 +0000[diff] [blame]109 "\\$\\{link (([a-zA-Z_-]+)(\\.([a-zA-Z_\\.-]+))?)\\}");
David Chenac13e222016-02-24 22:17:42 +0000[diff] [blame]110
fwe2cc4ff52022-03-29 12:05:43 -0700[diff] [blame]111 public static final Pattern BLAZE_RULE_HEADING_LINK =
112 Pattern.compile("\\$\\{link (([a-zA-Z_-]+)\\#([a-zA-Z0-9_\\.-]+))\\}");
David Chen118ef032016-05-17 10:36:55 +0000[diff] [blame]113
David Chenac13e222016-02-24 22:17:42 +0000[diff] [blame]114 /**
Klaus Aehlig698401a2019-03-26 09:07:52 -0700[diff] [blame]115 * i.e.
116 * <!-- #FAMILY_SUMMARY -->
117 */
118 public static final Pattern FAMILY_SUMMARY_START =
119 Pattern.compile("([\\s]*/\\*)?[\\s]*\\<!--[\\s]*#FAMILY_SUMMARY[\\s]*--\\>[\\s]*");
120
121 /**
122 * i.e.
123 * <!-- #END_FAMILY_SUMMARY -->
124 */
125 public static final Pattern FAMILY_SUMMARY_END =
126 Pattern.compile("[\\s]*\\<!--[\\s]*#END_FAMILY_SUMMARY[\\s]*--\\>[\\s]*(\\*/[\\s]*)?");
127
128 /**
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]129 * i.e. <!-- #BLAZE_RULE(NAME = RULE_NAME, TYPE = RULE_TYPE, FAMILY = RULE_FAMILY) -->
130 * i.e. <!-- #BLAZE_RULE(...)[DEPRECATED] -->
131 */
132 public static final Pattern BLAZE_RULE_START = Pattern.compile(
133 "^[\\s]*/\\*[\\s]*\\<!\\-\\-[\\s]*#BLAZE_RULE[\\s]*\\(([\\w\\s=,+/()-]+)\\)"
134 + "(\\[[\\w,]+\\])?[\\s]*\\-\\-\\>");
135 /**
136 * i.e. <!-- #END_BLAZE_RULE -->
137 */
138 public static final Pattern BLAZE_RULE_END = Pattern.compile(
139 "^[\\s]*\\<!\\-\\-[\\s]*#END_BLAZE_RULE[\\s]*\\-\\-\\>[\\s]*\\*/");
140 /**
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]141 * i.e. <!-- #BLAZE_RULE(RULE_NAME).VARIABLE_NAME -->
142 */
143 public static final Pattern BLAZE_RULE_VAR_START = Pattern.compile(
144 "^[\\s]*/\\*[\\s]*\\<!\\-\\-[\\s]*#BLAZE_RULE\\(([\\w\\$]+)\\)\\.([\\w]+)[\\s]*\\-\\-\\>");
145 /**
146 * i.e. <!-- #END_BLAZE_RULE.VARIABLE_NAME -->
147 */
148 public static final Pattern BLAZE_RULE_VAR_END = Pattern.compile(
149 "^[\\s]*\\<!\\-\\-[\\s]*#END_BLAZE_RULE\\.([\\w]+)[\\s]*\\-\\-\\>[\\s]*\\*/");
150 /**
151 * i.e. <!-- #BLAZE_RULE(RULE_NAME).ATTRIBUTE(ATTR_NAME) -->
152 * i.e. <!-- #BLAZE_RULE(RULE_NAME).ATTRIBUTE(ATTR_NAME)[DEPRECATED] -->
153 */
154 public static final Pattern BLAZE_RULE_ATTR_START = Pattern.compile(
155 "^[\\s]*/\\*[\\s]*\\<!\\-\\-[\\s]*#BLAZE_RULE\\(([\\w\\$]+)\\)\\."
156 + "ATTRIBUTE\\(([\\w]+)\\)(\\[[\\w,]+\\])?[\\s]*\\-\\-\\>");
157 /**
158 * i.e. <!-- #END_BLAZE_RULE.ATTRIBUTE -->
159 */
160 public static final Pattern BLAZE_RULE_ATTR_END = Pattern.compile(
161 "^[\\s]*\\<!\\-\\-[\\s]*#END_BLAZE_RULE\\.ATTRIBUTE[\\s]*\\-\\-\\>[\\s]*\\*/");
162
Laszlo Csomora5a112032015-03-10 09:43:49 +0000[diff] [blame]163 /** e.g. "[DEPRECATED]" in &lt;!-- #BLAZE_RULE(...).ATTRIBUTE(...)[DEPRECATED] --&gt; */
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]164 public static final Pattern BLAZE_RULE_FLAGS = Pattern.compile("^.*\\[(.*)\\].*$");
165
Googler50966222022-01-31 17:38:35 -0800[diff] [blame]166 public static final ImmutableMap<String, Integer> ATTRIBUTE_ORDERING =
167 ImmutableMap.<String, Integer>builder()
168 .put("name", -99)
169 .put("deps", -98)
170 .put("src", -97)
171 .put("srcs", -96)
172 .put("data", -95)
173 .put("resource", -94)
174 .put("resources", -93)
175 .put("out", -92)
176 .put("outs", -91)
177 .put("hdrs", -90)
178 .buildOrThrow();
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]179
vladmos18926772017-12-18 06:42:21 -0800[diff] [blame]180 // The following variables are not constants as they can be overridden from
laurentlbf0700282020-04-21 10:13:29 -0700[diff] [blame]181 // StarlarkDocumentationProcessor#parseOptions
fwebcf5b1752022-03-07 14:24:39 -0800[diff] [blame]182 // Their purpose is to allow generated Starlark documentation to link into the build encyclopedia.
vladmos18926772017-12-18 06:42:21 -0800[diff] [blame]183
fwebcf5b1752022-03-07 14:24:39 -0800[diff] [blame]184 // Root directory of *narrative* Starlark documentation files such as rules.md
185 public static String starlarkDocsRoot = "/rules";
vladmos18926772017-12-18 06:42:21 -0800[diff] [blame]186
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100[diff] [blame]187 static String toCommandLineFormat(String cmdDoc) {
188 // Replace html <br> tags with line breaks
189 cmdDoc = cmdDoc.replaceAll("(<br>|<br[\\s]*/>)", "\n") + "\n";
190 // Replace other links <a href=".*">s with human readable links
191 cmdDoc = cmdDoc.replaceAll("\\<a href=\"([^\"]+)\">[^\\<]*\\</a\\>", "$1");
192 // Delete other html tags
193 cmdDoc = cmdDoc.replaceAll("\\<[/]?[^\\>]+\\>", "");
194 // Delete docgen variables
195 cmdDoc = cmdDoc.replaceAll("\\$\\{[\\w_]+\\}", "");
196 // Substitute more than 2 line breaks in a row with 2 line breaks
197 cmdDoc = cmdDoc.replaceAll("[\\n]{2,}", "\n\n");
198 // Ensure that the doc starts and ends with exactly two line breaks
199 cmdDoc = cmdDoc.replaceAll("^[\\n]+", "\n\n");
200 cmdDoc = cmdDoc.replaceAll("[\\n]+$", "\n\n");
201 return cmdDoc;
202 }
203
204 static String removeDuplicatedNewLines(String doc) {
205 return doc.replaceAll("[\\n][\\s]*[\\n]", "\n");
206 }
207}