From 85d3a87ce4dd3cb0ad693aea413a56d96bc35ebe Mon Sep 17 00:00:00 2001
From: Enno <458526+ennru@users.noreply.github.com>
Date: Thu, 15 Aug 2019 07:05:01 +0200
Subject: [PATCH] FilterLabels: off for unlabeled includes (#345)
* FilterLabels: off for unlabeled includes
* Allow forcing `filterLabels` even for whole files
---
.../lightbend/paradox/ParadoxProcessor.scala | 4 +-
.../paradox/markdown/Directive.scala | 13 ++-
docs/src/main/paradox/directives/snippets.md | 27 ++++++
.../src/main/paradox/code-samples/Hello.scala | 2 -
.../paradox/snippets/expected/reference.html | 1 +
.../snippets/src/main/paradox/reference.md | 4 +-
.../src/test/resources/reference.conf | 4 +-
.../paradox/markdown/SnipDirectiveSpec.scala | 90 +++++++++++++++++++
8 files changed, 135 insertions(+), 10 deletions(-)
diff --git a/core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala b/core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala
index aeb2749b..77875552 100644
--- a/core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala
+++ b/core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala
@@ -240,9 +240,7 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
}
val includeFile = SourceDirective.resolveFile("include", source, file, properties)
val frontin = Frontin(includeFile)
- val filterLabels = include.attributes.booleanValue(
- "filterLabels",
- properties.get("include.filterLabels").exists(_ == "true"))
+ val filterLabels = Directive.filterLabels("include", include.attributes, labels, properties)
val (text, snippetLang) = Snippet(includeFile, labels, filterLabels)
// I guess we could support multiple markup languages in future...
if (snippetLang != "md" && snippetLang != "markdown") {
diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala
index 273092ca..a4d382a3 100644
--- a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala
+++ b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala
@@ -58,6 +58,15 @@ abstract class Directive {
def render(node: DirectiveNode, visitor: Visitor, printer: Printer): Unit
}
+object Directive {
+ def filterLabels(prefix: String, attributes: DirectiveAttributes, labels: Seq[String], properties: Map[String, String]): Boolean = attributes.value("filterLabels", "") match {
+ case "true" | "on" | "yes" => true
+ case "false" | "off" | "no" => false
+ case "" => labels.nonEmpty && properties.get(s"$prefix.filterLabels").forall(_ == "true")
+ }
+
+}
+
/**
* Inline directive.
*/
@@ -393,7 +402,7 @@ case class SnipDirective(page: Page, variables: Map[String, String])
try {
val labels = node.attributes.values("identifier").asScala
val source = resolvedSource(node, page)
- val filterLabels = node.attributes.booleanValue("filterLabels", variables.get("snip.filterLabels").forall(_ == "true"))
+ val filterLabels = Directive.filterLabels("snip", node.attributes, labels, variables)
val file = resolveFile("snip", source, page, variables)
val (text, snippetLang) = Snippet(file, labels, filterLabels)
val lang = Option(node.attributes.value("type")).getOrElse(snippetLang)
@@ -451,7 +460,7 @@ case class FiddleDirective(page: Page, variables: Map[String, String])
val source = resolvedSource(node, page)
val file = resolveFile("fiddle", source, page, variables)
- val filterLabels = node.attributes.booleanValue("filterLabels", variables.get("fiddle.filterLabels").forall(_ == "true"))
+ val filterLabels = Directive.filterLabels("fiddle", node.attributes, labels, variables)
val (code, _) = Snippet(file, labels, filterLabels)
printer.println.print(s"""
diff --git a/docs/src/main/paradox/directives/snippets.md b/docs/src/main/paradox/directives/snippets.md
index 2d21a7bf..4e61541c 100644
--- a/docs/src/main/paradox/directives/snippets.md
+++ b/docs/src/main/paradox/directives/snippets.md
@@ -50,6 +50,33 @@ Maven
Gradle
: @@snip [build.gradle](/docs/src/main/resources/build.gradle) { #setup_example }
+
+#### Label filtering
+
+Any lines containing `#labels` within the included snippet are filtered out. This filtering can
+be switched off with `filterLabels`. It is off by default for snippets that include the whole file
+(without limiting the snippet by providing a label) and can be set to `true` to overwrite that.
+
+```markdown
+@@snip [example.log](example.log) { #example-log filterLabels=false }
+```
+
+The default value is set with the `include.filterLabels` property.
+
+```
+paradoxProperties += "snip.filterLabels" -> "false"
+```
+
+This label filtering applies to @ref:[Markdown includes](includes.md) and @ref:[Fiddle includes](fiddles.md), as well.
+
+```
+paradoxProperties += "include.filterLabels" -> "false",
+paradoxProperties += "fiddle.filterLabels" -> "false"
+```
+
+
+#### Syntax highlighting
+
By default, Paradox uses Prettify to highlight code and will try to detect the
language of the snippet using the file extension. In cases where a snippet
should not be highlighted set `type=text` in the directive's attribute section:
diff --git a/plugin/src/sbt-test/paradox/snippet-noindent-writer/src/main/paradox/code-samples/Hello.scala b/plugin/src/sbt-test/paradox/snippet-noindent-writer/src/main/paradox/code-samples/Hello.scala
index 3d426888..eca13ee7 100644
--- a/plugin/src/sbt-test/paradox/snippet-noindent-writer/src/main/paradox/code-samples/Hello.scala
+++ b/plugin/src/sbt-test/paradox/snippet-noindent-writer/src/main/paradox/code-samples/Hello.scala
@@ -1,4 +1,3 @@
-// #hello_example
object Hello extends App {
def say(str: String): Unit = {
println(str)
@@ -6,4 +5,3 @@ object Hello extends App {
say("hello")
}
-// #hello_example
\ No newline at end of file
diff --git a/plugin/src/sbt-test/paradox/snippets/expected/reference.html b/plugin/src/sbt-test/paradox/snippets/expected/reference.html
index bdaab0f8..b1c7fa11 100644
--- a/plugin/src/sbt-test/paradox/snippets/expected/reference.html
+++ b/plugin/src/sbt-test/paradox/snippets/expected/reference.html
@@ -5,5 +5,6 @@
# this snip is a snap
snip = "snap"
}
+
# this snip is a snap
snip = "snap"
diff --git a/plugin/src/sbt-test/paradox/snippets/src/main/paradox/reference.md b/plugin/src/sbt-test/paradox/snippets/src/main/paradox/reference.md
index 3260b162..a2c725d9 100644
--- a/plugin/src/sbt-test/paradox/snippets/src/main/paradox/reference.md
+++ b/plugin/src/sbt-test/paradox/snippets/src/main/paradox/reference.md
@@ -1,3 +1,5 @@
-@@ snip [whole file](../../test/resources/reference.conf)
+@@ snip [whole file](../../test/resources/reference.conf) { filterLabels=true }
+
+
@@ snip [snip snippet](../../test/resources/reference.conf) { #snip }
diff --git a/plugin/src/sbt-test/paradox/snippets/src/test/resources/reference.conf b/plugin/src/sbt-test/paradox/snippets/src/test/resources/reference.conf
index 70b1b08c..4221bb2c 100644
--- a/plugin/src/sbt-test/paradox/snippets/src/test/resources/reference.conf
+++ b/plugin/src/sbt-test/paradox/snippets/src/test/resources/reference.conf
@@ -1,11 +1,11 @@
# This should be included
#and this as well
-#and-this-line-should-be-skipped
+#and-this-line-should-be-skipped-when-using-labels
snippets {
#snip
# this snip is a snap
- #and-this-line-should-be-skipped
+ #and-this-line-should-be-skipped-when-using-labels
snip = "snap"
#snip
}
diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/SnipDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/SnipDirectiveSpec.scala
index 50a1784c..8d90c6ab 100644
--- a/tests/src/test/scala/com/lightbend/paradox/markdown/SnipDirectiveSpec.scala
+++ b/tests/src/test/scala/com/lightbend/paradox/markdown/SnipDirectiveSpec.scala
@@ -154,6 +154,96 @@ class SnipDirectiveSpec extends MarkdownBaseSpec {
|""")
}
+ it should "include labels when including the whole file" in {
+ markdown("""@@snip[example.scala](tests/src/test/scala/com/lightbend/paradox/markdown/example.scala)""") shouldEqual html(
+ """
+ |
+ |/*
+ | * Copyright © 2015 - 2019 Lightbend, Inc. <http://www.lightbend.com>
+ | *
+ | * 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.lightbend.paradox.markdown
+ |
+ |//#github-path-link
+ |object GithubPathLink {
+ | //#github-neither-path-link
+ | type Neither[A, B] = Nothing
+ | //#github-neither-path-link
+ |}
+ |//#github-path-link
+ |
+ |//#example
+ |object example extends App {
+ | println("Hello, World!")
+ |}
+ |//#example
+ |
+ |object IndentedExample {
+ | //#indented-example
+ | case object Dent
+ | //#indented-example
+ |
+ | object EventMore {
+ | //#indented-example
+ | case object DoubleDent
+ | //#indented-example
+ | }
+ |}
+ |
+ |//#multi-indented-example
+ |//#some-other-anchor
+ |object AnotherIndentedExample {
+ | //#multi-indented-example
+ |
+ | def notRendered(): Unit = {
+ | }
+ |
+ | //#multi-indented-example
+ | def rendered(): Unit = {
+ | }
+ | //#some-other-anchor
+ | //#multi-indented-example
+ |
+ | def alsoNotRendered(): Unit = {
+ |
+ | }
+ | //#multi-indented-example
+ |}
+ |//#multi-indented-example
+ |
+ |//#multi-indented-example
+ |class AnotherClass
+ |//#multi-indented-example
+ |
+ |// check empty line with indented blocks!
+ |// format: OFF
+ | //#multi-indented-example
+ |
+ | //#multi-indented-example
+ |// format: ON
+ |
+ |
+ |//#example-with-label
+ |object Constants {
+ | val someString = " #foo "
+ |}
+ |//#example-with-label
+ |
"""
+ )
+ }
+
it should "filter labels by default" in {
markdown("""@@snip[example.scala](tests/src/test/scala/com/lightbend/paradox/markdown/example.scala) { #example-with-label }""") shouldEqual html(
"""