Merge branch 'main' into update/scala-library-2.13.5

Author: steinybot

.github/workflows/ci.yml

@@ -52,27 +52,15 @@ jobs:
       - name: Check that workflows are up to date
         run: sbt ++${{ matrix.scala }} githubWorkflowCheck
 
-      - name: Check formatting and style
-        run: sbt ++${{ matrix.scala }} scalafmtCheckAll scalastyle
-
-      - name: Check version adheres to the policy
-        run: sbt ++${{ matrix.scala }} versionPolicyCheck
-
-      - name: Check documentation has been generated
-        run: sbt ++${{ matrix.scala }} mdocCheck
-
-      - name: Check dependencies
-        run: sbt ++${{ matrix.scala }} evicted undeclaredCompileDependenciesTest unusedCompileDependenciesTest dependencyCheckAggregate
-
-      - name: Build and test
-        run: sbt ++${{ matrix.scala }} test
+      - name: Build, test and check libraries
+        run: sbt ++${{ matrix.scala }} check
 
       - name: Build and test sbt plugin
         if: matrix.scala == '2.12.13'
         run: sbt ++${{ matrix.scala }} scripted
 
       - name: Compress target directories
-        run: tar cf targets.tar sbt/target target doc-templates/target cli/target core/target project/target
+        run: tar cf targets.tar sbt/target meta/integration-tests/target target meta/docs/target cli/target core/target example/target project/target
 
       - name: Upload target directories
         uses: actions/upload-artifact@v2

README.md

@@ -1,7 +1,8 @@
 # Scala2PlantUML
 
-[![Continuous Integration](https://github.com/BotTech/scala2plantuml/actions/workflows/ci.yml/badge.svg)](https://github.com/BotTech/scala2plantuml/actions/workflows/ci.yml)
-![Scala2PlantUML Version](https://img.shields.io/maven-central/v/nz.co.bottech/scala2plantuml_2.13?label=Scala2PlantUML)
+[![Build badge](https://img.shields.io/github/workflow/status/BotTech/scala2plantuml/Continuous%20Integration/main)](https://github.com/BotTech/scala2plantuml/actions/workflows/ci.yml)
+[![Maven-Central badge](https://img.shields.io/maven-central/v/nz.co.bottech/scala2plantuml_2.13)](https://search.maven.org/search?q=g:nz.co.bottech%20a:*scala2plantuml*)
+[![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)
 
 Scala2PlantUML generates [PlantUML] diagrams from Scala code.
 
@@ -10,6 +11,40 @@ It comes as a standalone library, a CLI tool and an sbt plugin.
 Scala2PlantUML consumes [SemanticDB] files so you will need to know how to create those or simply follow the sbt setup
 instructions below.
 
+## Example
+
+```shell
+scala2plantuml \
+  --url 'https://repo1.maven.org/maven2/nz/co/bottech/scala2plantuml-example_2.13/0.2.0/scala2plantuml-example_2.13-0.2.0.jar'\
+  --project example \
+  "nz/co/bottech/scala2plantuml/example/Main."
+```
+
+```text
+@startuml
+class A extends B {
+  + {method} <init>
+  + {method} b
+}
+A o-- C
+interface B {
+  + {abstract} {method} b
+}
+B o-- C
+class C {
+  + {method} <init>
+  + {field} value
+}
+C o-- A
+class Main {
+  + {static} {field} a
+}
+Main o-- A
+@enduml
+```
+
+![Example Class Diagram](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/BotTech/scala2plantuml/main/example/example.md)
+
 ## sbt
 
 ### Enable SemanticDB
@@ -36,9 +71,24 @@ For most use cases you should add Scala2PlantUML as a global plugin since your b
 Create `~/.sbt/1.0/plugins/scala2PlantUML.sbt` containing:
 
 ```text
-addSbtPlugin("nz.co.bottech" % "sbt-scala2plantuml" % "0.1.12")
+addSbtPlugin("nz.co.bottech" % "sbt-scala2plantuml" % "0.2.0")
+```
+
+### Generate the Diagram
+
+Run the `scala2PlantUML` task from sbt:
+
+```sbt
+scala2PlantUML "com/example/Foo#"
 ```
 
+This accepts the following arguments:
+- `--include`
+- `--exclude`
+- `--output`
+
+Refer to the [CLI Usage](#usage) for the definition of these arguments.
+
 ## CLI
 
 ### Install
@@ -51,19 +101,23 @@ cs install --channel https://git.io/Jqv1i scala2plantuml
 
 ### Usage
 
+```shell
+scala2plantuml --help
+```
+
 ```text
-Scala2PlantUML version 0.1.12
+Scala2PlantUML version 0.2.0
 Usage: scala2plantuml [options] symbol
 
 Scala2PlantUML generates PlantUML Class Diagrams from Scala SemanticDB files.
 
   symbol                   The symbol to use as the starting point for generating the diagram.
-
+                           
                            To get a symbol from a class name, convert the package name separate '.' to '/' and add a '#'
                            suffix. For an object use a suffix of '.'.
-
+                           
                            See https://scalameta.org/docs/semanticdb/specification.html#symbol-1 for the full syntax.
-
+                           
                            Examples:
                              'com/example/Foo#' (class com.example.Foo)
                              'com/example/Foo.' (object com.example.Foo)
@@ -77,16 +131,16 @@ The pattern supports two wildcards:
 2) *  (matches all characters except for '/')
 
   -i, --include <pattern>  Only include symbols that match the pattern.
-
+                           
                            Default: '**'
-
+                           
                            Example:
                              --include 'com/example/**/model/*'
 
   -e, --exclude <pattern>  Excludes all symbols that match the pattern.
-
+                           
                            Default: 'scala/**', 'java/**'
-
+                           
                            Example:
                              --exclude 'com/example/**/data/*'
 
@@ -96,62 +150,73 @@ Each of these can be provided multiple times.
 By default, the classpath that was used when executing Scala2PlantUML is also used.
 
   -d, --dir <dir>          Directories of the SemanticDB target roots containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --dir 'my-project/target/scala-2.13/meta'
 
   -j, --jar <jar>          JAR containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --jar 'foo.jar'
 
   -u, --url <url>          A URL to a JAR containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --url 'https://repo1.maven.org/maven2/com/example/foo/foo_2.13/1.0.0/foo_2.13-1.0.0-semanticdb.jar'
 
 The --project and --source options specify where within the search locations the SemanticDB files can be found.
 Each of these can be provided multiple times. The result will be all combinations of projects and source roots.
 
   -p, --project <project>  The name of the projects that have SemanticDB files.
-
+                           
                            The project name will be used when looking for SemanticDB files such as:
                            META-INF/semanticdb/<project>/<source>/*.semanticdb
-
+                           
                            An empty project name will search in:
                            META-INF/semanticdb/<source>/*.semanticdb
-
+                           
                            Default: ''
-
+                           
                            Example:
                              --project my-project
 
   -s, --source <source>    The directory relative to the project where the source files were located.
-
+                           
                            The source will be used when looking for SemanticDB files such as
                            META-INF/semanticdb/<project>/<source>/*.semanticdb.
-
+                           
                            Default: src/main/scala
-
+                           
                            Example:
                              --source 'source/scala'
 
-  -o, --output <file>      Write the output to the given file.
+  -l, --max-level <level>  The maximum number of levels that will be traversed when following symbol references.
+                           
+                           This means that parent symbols that would be beyond the max level will not be shown.
+                           
+                           A diagram with a max-level of 1 will only contain the initial symbol.
+                           
+                           Default: Unlimited
+                           
+                           Example:
+                             --max-level 3
 
+  -o, --output <file>      Write the output to the given file.
+                           
                            Example:
                              --output docs/diagrams/my-project.puml
 
   -c, --colour <value>     Enables coloured output.
-
+                           
                            Default: true
-
+                           
                            Example:
                              --colour false
 
   -v, --verbose            Increases the log level.
-
+                           
                            This can be provided twice for the most verbose logging.
-
+                           
                            Example:
                              -vv
 
@@ -163,6 +228,18 @@ Each of these can be provided multiple times. The result will be all combination
 
 > 🚧 TODO: Document Library.
 
+## Limitations
+
+- Only class diagrams are supported.
+- Only inheritance or aggregations are supported, compositions are shown as aggregations.
+- Aggregations are shown between types not between fields. There is a [bug][namespaced field links] in PlantUML which
+  prevents us from being able to do this reliably.
+- There is no reliable way to determine the path to a SemanticDB file from any symbol.
+  If Scala2PlantUML is unable to find your symbols then the following may help:
+  - Only have a single top level type in each file.
+  - Ensure that the file name matches the type name.
+  - Nest any subclasses of a sealed class within the companion object of the sealed class.
+
 [coursier]: https://get-coursier.io/docs/cli-install
 [plantuml]: https://plantuml.com/
 [semanticdb]: https://scalameta.org/docs/semanticdb/guide.html