LOG4J2-2296: Add minimal website generator config
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/commit/b510c122 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/tree/b510c122 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/diff/b510c122 Branch: refs/heads/master Commit: b510c122e94c6cfb0b957f6a8ed83ecdc1057142 Parents: 53cfa5d Author: Matt Sicker <[email protected]> Authored: Thu Mar 29 20:13:58 2018 -0500 Committer: Matt Sicker <[email protected]> Committed: Thu Mar 29 20:13:58 2018 -0500 ---------------------------------------------------------------------- build.sbt | 1 + log4j-api-scala_2.10/src/site/markdown/index.md | 74 ---------------- log4j-api-scala_2.11/src/site/markdown/index.md | 74 ---------------- log4j-api-scala_2.12/src/site/markdown/index.md | 74 ---------------- log4j-api-scala_2.13/src/site/markdown/index.md | 74 ---------------- project/plugins.sbt | 2 + src/asciidoctor/index.adoc | 88 ++++++++++++++++++++ 7 files changed, 91 insertions(+), 296 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/build.sbt ---------------------------------------------------------------------- diff --git a/build.sbt b/build.sbt index 118337c..6dba52b 100644 --- a/build.sbt +++ b/build.sbt @@ -96,6 +96,7 @@ lazy val root = (project in file(".")) .settings(releaseSettings: _*) .settings(apiDependencies: _*) .settings(apiInputFiles: _*) + .enablePlugins(AsciidoctorPlugin) // .enablePlugins(SbtOsgi) // .settings(bundleSettings: _*) http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/log4j-api-scala_2.10/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/log4j-api-scala_2.10/src/site/markdown/index.md b/log4j-api-scala_2.10/src/site/markdown/index.md deleted file mode 100644 index ce84e3d..0000000 --- a/log4j-api-scala_2.10/src/site/markdown/index.md +++ /dev/null @@ -1,74 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---> -# Log4j Scala 2.10 API - -## Requirements - -Log4j Scala API for Scala 2.10 requires Log4j API, Java 7, the Scala runtime -library, and the Scala reflection library. To use Log4j as a logging implementation, -then Log4j Core must also be included. Instructions on using these dependencies are -in the [dependency information page][dependencies], and additional information is -included in the [Log4j artifacts][artifacts] page. - -## Example Usage - -<pre class="prettyprint linenums"> -import org.apache.logging.log4j.scala.Logging -import org.apache.logging.log4j.Level - -class MyClass extends BaseClass with Logging { - def doStuff(): Unit = { - logger.info("Doing stuff") - } - def doStuffWithLevel(level: Level): Unit = { - logger(level, "Doing stuff with arbitrary level") - } -} -</pre> - -## Configuration - -Log4j Scala 2.10 API uses the standard [Log4j configuration][configuration] -plugins. This supports XML, properties files, and a configuration builder DSL by -default, and it optionally supports JSON and YAML formats with some additional -Jackson dependencies. - -## Substituting Parameters - -In the Java API, parameters to a log message are interpolated using various -strategies. In the Scala API, [string interpolation][interpolation] is used -instead. As all logger methods are implemented as macros, string construction and -method invocations will only occur when logging is enabled for the given log -level. For example: - -<pre class="prettyprint linenums"> -logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") -</pre> - -## Logger Names - -Most logging implementations use a hierarchical scheme for matching logger names -with logging configuration. In this scheme the logger name hierarchy is -represented by '.' characters in the logger name, in a fashion very similar to -the hierarchy used for Java/Scala package names. The [`Logging` trait][logging] -will automatically name the Logger accordingly to the class it is being used in. - -[dependencies]: dependency-info.html -[artifacts]: ../maven-artifacts.html -[configuration]: ../configuration.html -[interpolation]: http://docs.scala-lang.org/overviews/core/string-interpolation.html -[logging]: scaladocs/index.html#org.apache.logging.log4j.scala.Logging \ No newline at end of file http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/log4j-api-scala_2.11/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/log4j-api-scala_2.11/src/site/markdown/index.md b/log4j-api-scala_2.11/src/site/markdown/index.md deleted file mode 100644 index 7ababf1..0000000 --- a/log4j-api-scala_2.11/src/site/markdown/index.md +++ /dev/null @@ -1,74 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---> -# Log4j Scala 2.11 API - -## Requirements - -Log4j Scala API for Scala 2.11 requires Log4j API, Java 7, the Scala runtime -library, and the Scala reflection library. To use Log4j as a logging implementation, -then Log4j Core must also be included. Instructions on using these dependencies are -in the [dependency information page][dependencies], and additional information is -included in the [Log4j artifacts][artifacts] page. - -## Example Usage - -<pre class="prettyprint linenums"> -import org.apache.logging.log4j.scala.Logging -import org.apache.logging.log4j.Level - -class MyClass extends BaseClass with Logging { - def doStuff(): Unit = { - logger.info("Doing stuff") - } - def doStuffWithLevel(level: Level): Unit = { - logger(level, "Doing stuff with arbitrary level") - } -} -</pre> - -## Configuration - -Log4j Scala 2.11 API uses the standard [Log4j configuration][configuration] -plugins. This supports XML, properties files, and a configuration builder DSL by -default, and it optionally supports JSON and YAML formats with some additional -Jackson dependencies. - -## Substituting Parameters - -In the Java API, parameters to a log message are interpolated using various -strategies. In the Scala API, [string interpolation][interpolation] is used -instead. As all logger methods are implemented as macros, string construction and -method invocations will only occur when logging is enabled for the given log -level. For example: - -<pre class="prettyprint linenums"> -logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") -</pre> - -## Logger Names - -Most logging implementations use a hierarchical scheme for matching logger names -with logging configuration. In this scheme the logger name hierarchy is -represented by '.' characters in the logger name, in a fashion very similar to -the hierarchy used for Java/Scala package names. The [`Logging` trait][logging] -will automatically name the Logger accordingly to the class it is being used in. - -[dependencies]: dependency-info.html -[artifacts]: ../maven-artifacts.html -[configuration]: ../configuration.html -[interpolation]: http://docs.scala-lang.org/overviews/core/string-interpolation.html -[logging]: scaladocs/index.html#org.apache.logging.log4j.scala.Logging \ No newline at end of file http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/log4j-api-scala_2.12/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/log4j-api-scala_2.12/src/site/markdown/index.md b/log4j-api-scala_2.12/src/site/markdown/index.md deleted file mode 100644 index 7acf397..0000000 --- a/log4j-api-scala_2.12/src/site/markdown/index.md +++ /dev/null @@ -1,74 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---> -# Log4j Scala 2.12 API - -## Requirements - -Log4j Scala API for Scala 2.12 requires Log4j API, Java 8, the Scala runtime -library, and the Scala reflection library. To use Log4j as a logging implementation, -then Log4j Core must also be included. Instructions on using these dependencies are -in the [dependency information page][dependencies], and additional information is -included in the [Log4j artifacts][artifacts] page. - -## Example Usage - -<pre class="prettyprint linenums"> -import org.apache.logging.log4j.scala.Logging -import org.apache.logging.log4j.Level - -class MyClass extends BaseClass with Logging { - def doStuff(): Unit = { - logger.info("Doing stuff") - } - def doStuffWithLevel(level: Level): Unit = { - logger(level, "Doing stuff with arbitrary level") - } -} -</pre> - -## Configuration - -Log4j Scala 2.12 API uses the standard [Log4j configuration][configuration] -plugins. This supports XML, properties files, and a configuration builder DSL by -default, and it optionally supports JSON and YAML formats with some additional -Jackson dependencies. - -## Substituting Parameters - -In the Java API, parameters to a log message are interpolated using various -strategies. In the Scala API, [string interpolation][interpolation] is used -instead. As all logger methods are implemented as macros, string construction and -method invocations will only occur when logging is enabled for the given log -level. For example: - -<pre class="prettyprint linenums"> -logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") -</pre> - -## Logger Names - -Most logging implementations use a hierarchical scheme for matching logger names -with logging configuration. In this scheme the logger name hierarchy is -represented by '.' characters in the logger name, in a fashion very similar to -the hierarchy used for Java/Scala package names. The [`Logging` trait][logging] -will automatically name the Logger accordingly to the class it is being used in. - -[dependencies]: dependency-info.html -[artifacts]: ../maven-artifacts.html -[configuration]: ../configuration.html -[interpolation]: http://docs.scala-lang.org/overviews/core/string-interpolation.html -[logging]: scaladocs/org/apache/logging/log4j/scala/Logging.html \ No newline at end of file http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/log4j-api-scala_2.13/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/log4j-api-scala_2.13/src/site/markdown/index.md b/log4j-api-scala_2.13/src/site/markdown/index.md deleted file mode 100644 index 7acf397..0000000 --- a/log4j-api-scala_2.13/src/site/markdown/index.md +++ /dev/null @@ -1,74 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---> -# Log4j Scala 2.12 API - -## Requirements - -Log4j Scala API for Scala 2.12 requires Log4j API, Java 8, the Scala runtime -library, and the Scala reflection library. To use Log4j as a logging implementation, -then Log4j Core must also be included. Instructions on using these dependencies are -in the [dependency information page][dependencies], and additional information is -included in the [Log4j artifacts][artifacts] page. - -## Example Usage - -<pre class="prettyprint linenums"> -import org.apache.logging.log4j.scala.Logging -import org.apache.logging.log4j.Level - -class MyClass extends BaseClass with Logging { - def doStuff(): Unit = { - logger.info("Doing stuff") - } - def doStuffWithLevel(level: Level): Unit = { - logger(level, "Doing stuff with arbitrary level") - } -} -</pre> - -## Configuration - -Log4j Scala 2.12 API uses the standard [Log4j configuration][configuration] -plugins. This supports XML, properties files, and a configuration builder DSL by -default, and it optionally supports JSON and YAML formats with some additional -Jackson dependencies. - -## Substituting Parameters - -In the Java API, parameters to a log message are interpolated using various -strategies. In the Scala API, [string interpolation][interpolation] is used -instead. As all logger methods are implemented as macros, string construction and -method invocations will only occur when logging is enabled for the given log -level. For example: - -<pre class="prettyprint linenums"> -logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") -</pre> - -## Logger Names - -Most logging implementations use a hierarchical scheme for matching logger names -with logging configuration. In this scheme the logger name hierarchy is -represented by '.' characters in the logger name, in a fashion very similar to -the hierarchy used for Java/Scala package names. The [`Logging` trait][logging] -will automatically name the Logger accordingly to the class it is being used in. - -[dependencies]: dependency-info.html -[artifacts]: ../maven-artifacts.html -[configuration]: ../configuration.html -[interpolation]: http://docs.scala-lang.org/overviews/core/string-interpolation.html -[logging]: scaladocs/org/apache/logging/log4j/scala/Logging.html \ No newline at end of file http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/project/plugins.sbt ---------------------------------------------------------------------- diff --git a/project/plugins.sbt b/project/plugins.sbt index 5e55c9d..df90981 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -1,3 +1,5 @@ addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.1") addSbtPlugin("com.github.gseitz" % "sbt-release" % "1.0.8") addSbtPlugin("com.typesafe.sbt" % "sbt-license-report" % "1.2.0") +addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.2") +//addSbtPlugin("com.typesafe.sbt" % "sbt-osgi" % "0.9.3") http://git-wip-us.apache.org/repos/asf/logging-log4j-scala/blob/b510c122/src/asciidoctor/index.adoc ---------------------------------------------------------------------- diff --git a/src/asciidoctor/index.adoc b/src/asciidoctor/index.adoc new file mode 100644 index 0000000..b9595af --- /dev/null +++ b/src/asciidoctor/index.adoc @@ -0,0 +1,88 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. +//// += Apache Log4j Scala API + +Log4j Scala API is a Scala logging facade based on Log4j 2. +Support for Scala versions 2.10, 2.11, and 2.12 are provided, and experimental support for pre-release versions of 2.13 is also provided. +Log4j Scala API uses Log4j 2.x as its logging backend by default, but this can also be replaced with compatible libraries (e.g., Logback). +While this library is not required to use Log4j API in Scala, it does provide idiomatic Scala APIs which are friendlier to use in Scala programs than the Java APIs. + +== Usage + +Log4j Scala API requires Log4j API. An example SBT dependency setup: + +.build.sbt +[source,scala] +---- +libraryDependencies ++= Seq( + "org.apache.logging.log4j" %% "log4j-api-scala" % "11.0", + "org.apache.logging.log4j" % "log4j-api" % "2.11.0", + "org.apache.logging.log4j" % "log4j-core" % "2.11.0" % Runtime) +---- + +Using the Scala API is as simple as mixing in the `Logging` trait to your class. Example: + +[source,scala] +---- +import org.apache.logging.log4j.scala.Logging +import org.apache.logging.log4j.Level + +class MyClass extends BaseClass with Logging { + def doStuff(): Unit = { + logger.info("Doing stuff") + } + def doStuffWithLevel(level: Level): Unit = { + logger(level, "Doing stuff with arbitrary level") + } + def doStuffWithUser(user: User): Unit = { + logger.info(s"Doing stuff with ${user.getName}.") + } +} +---- + +== Configuration + +Log4j Scala API uses https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j configuration] by default. +This supports XML, properties files, and Java-based builders, as well as JSON and YAML with additional dependencies. + +== Substituting Parameters + +Unlike in Java, Scala provides native functionality for string interpolation https://docs.scala-lang.org/overviews/core/string-interpolation.html[beginning in Scala 2.10]. +As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks. +For example: + +[source,scala] +---- +logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}") +---- + +== Logger Names + +Most logging implementations use a hierarchical scheme for matching logger names with logging configuration. +In this scheme the logger name hierarchy is represented by '.' characters in the logger name, in a fashion very similar to the hierarchy used for Java/Scala package names. +The `Logging` trait will automatically name the Logger accordingly to the class it is being used in. + +//// +TODO: +* Apache logo +* Downloads page +* Changelog page +* License report +* Other reports? +* ScalaDocs links +* Project links +//// \ No newline at end of file
