From 1892677145c55f3e233a5dd16c695416b994a924 Mon Sep 17 00:00:00 2001 From: vladmos Date: Mon, 18 Dec 2017 06:42:21 -0800 Subject: Fix a documentation link PiperOrigin-RevId: 179416493 --- .../google/devtools/build/docgen/DocgenConsts.java | 13 ++++++--- .../docgen/SkylarkDocumentationProcessor.java | 5 +++- .../docgen/skylark/SkylarkBuiltinMethodDoc.java | 2 +- .../build/docgen/skylark/SkylarkDocUtils.java | 33 ++++++++++++++++++++++ .../build/docgen/skylark/SkylarkParamDoc.java | 3 +- .../build/lib/analysis/skylark/SkylarkAttr.java | 2 +- .../skylark/SkylarkRuleClassFunctions.java | 3 +- 7 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java (limited to 'src') diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java index d5e003715d..ebdf3f3cb2 100644 --- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java +++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java @@ -45,10 +45,6 @@ public class DocgenConsts { public static final String SKYLARK_OVERVIEW_TEMPLATE = "com/google/devtools/build/docgen/templates/skylark-overview.vm"; - // Build Encyclopedia documentation root - // Can be overridden from SkylarkDocumentationProcessor#parseOptions - public static String BEDocsRoot = "/versions/master/be"; - public static final String VAR_LEFT_PANEL = "LEFT_PANEL"; public static final String VAR_SECTION_BINARY = "SECTION_BINARY"; @@ -173,6 +169,15 @@ public class DocgenConsts { .put("hdrs", -90) .build(); + // The following variables are not constants as they can be overridden from + // SkylarkDocumentationProcessor#parseOptions + + // Build Encyclopedia documentation root + public static String BeDocsRoot = "/versions/master/be"; + + // Documentation files extension + public static String documentationExtension = "html"; + static String toCommandLineFormat(String cmdDoc) { // Replace html
tags with line breaks cmdDoc = cmdDoc.replaceAll("(
|)", "\n") + "\n"; diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java index f6525f6849..34a1b23810 100644 --- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java +++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java @@ -243,7 +243,10 @@ public final class SkylarkDocumentationProcessor { private static void parseOptions(String... args) { for (String arg : args) { if (arg.startsWith("--be_root=")) { - DocgenConsts.BEDocsRoot = arg.split("--be_root=", 2)[1]; + DocgenConsts.BeDocsRoot = arg.split("--be_root=", 2)[1]; + } + if (arg.startsWith("--doc_extension=")) { + DocgenConsts.documentationExtension = arg.split("--doc_extension=", 2)[1]; } } } diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java index e352fb3bc3..bcb52923f9 100644 --- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java +++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java @@ -53,7 +53,7 @@ public final class SkylarkBuiltinMethodDoc extends SkylarkMethodDoc { @Override public String getDocumentation() { - return annotation.doc(); + return SkylarkDocUtils.substituteVariables(annotation.doc()); } /** diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java new file mode 100644 index 0000000000..ac73f65596 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java @@ -0,0 +1,33 @@ +// Copyright 2014 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.devtools.build.docgen.skylark; + +import com.google.devtools.build.docgen.DocgenConsts; + +/** A utility class for the documentation generator. */ +public final class SkylarkDocUtils { + private SkylarkDocUtils() {} + + /** + * Substitute special variables in the documentation with their actual values + * + * @return a string with substituted variables + */ + static String substituteVariables(String documentation) { + return documentation + .replace("$BE_ROOT", DocgenConsts.BeDocsRoot) + .replace("$DOC_EXT", DocgenConsts.documentationExtension); + } +} diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java index d61aef65ad..74d26a9853 100644 --- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java +++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java @@ -13,7 +13,6 @@ // limitations under the License. package com.google.devtools.build.docgen.skylark; -import com.google.devtools.build.docgen.DocgenConsts; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.ParamType; @@ -74,6 +73,6 @@ public final class SkylarkParamDoc extends SkylarkDoc { @Override public String getDocumentation() { - return param.doc().replace("$BE_ROOT", DocgenConsts.BEDocsRoot); + return SkylarkDocUtils.substituteVariables(param.doc()); } } diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java index 82561c369b..d6c795fd72 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java @@ -639,7 +639,7 @@ public final class SkylarkAttr implements SkylarkValue { + "referred to by the label. " + "It is the only way to specify a dependency to another target. " + "If you need a dependency that the user cannot overwrite, " - + "make the attribute private.", + + "make the attribute private.", objectType = SkylarkAttr.class, returnType = Descriptor.class, parameters = { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java index 28c03130e5..82370f14d1 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java @@ -247,7 +247,8 @@ public class SkylarkRuleClassFunctions { + "Instantiate this provider with
" + "
"
             + "OutputGroupInfo(group1 = <files>, group2 = <files>...)
" - + "See Output Groups for more information" + + "See Output Groups " + + "for more information." ) private static final Provider outputGroupInfo = OutputGroupInfo.SKYLARK_CONSTRUCTOR; -- cgit v1.2.3