diff --git a/docs/0-installation/troubleshooting.md b/docs/0-installation/troubleshooting.md index 4d910f8..5ba047d 100644 --- a/docs/0-installation/troubleshooting.md +++ b/docs/0-installation/troubleshooting.md @@ -13,8 +13,7 @@ in [Sonatype](https://search.maven.org/search?q=g:io.github.ulitol97). If _sbt_ is failing to fetch @APP_INNER_NAME@, add the following to your configuration in `build.sbt`: -```scala -// Add dependency resolvers for Sonatype +```scala title="Add dependency resolvers for Sonatype" resolvers ++= Seq( Opts.resolver.sonatypeSnapshots, Opts.resolver.sonatypeReleases diff --git a/docs/1-getting_started/example.md b/docs/1-getting_started/example.md index ee63552..b67d4c8 100644 --- a/docs/1-getting_started/example.md +++ b/docs/1-getting_started/example.md @@ -8,10 +8,10 @@ title: Getting started The following is an example showing how to use @APP_NAME@ with: - A **List Extractor**, containing a list of RDF strings from which to form a - stream of RDF + stream of RDF data. - A **Validator**, configured with a _Schema_ and a _ValidationTrigger_ to - produce a stream of validation results -- A set of code blocks evaluating the stream items: + produce a stream of validation results. +- A set of code blocks evaluating the final stream items: - EvalMap: Print the items at the end of the processing pipeline - Error handling: Define error-recovering behaviour @@ -62,7 +62,7 @@ object Main extends IOApp.Simple { // 4. Start the validation stream app <- validator.validate // Init - .evalTap(IO.println) // Print each item + .evalMap(IO.println) // Print each item .handleErrorWith { error => // Handle each error Stream.eval( error match { diff --git a/docs/2-validators/validator_config.md b/docs/2-validators/validator_config.md index 3851d38..684d4a7 100644 --- a/docs/2-validators/validator_config.md +++ b/docs/2-validators/validator_config.md @@ -17,12 +17,12 @@ ValidatorConfiguration_ instance: #### Schema SHaclEX Schema against which the validation will be performed for all items processed by -this validator +this validator. #### Trigger SHaclEX ValidationTrigger against which the validation will be performed for all items -processed by this validator +processed by this validator. ### Optional parameters diff --git a/docs/3-extractor_model/predefined_extractors.md b/docs/3-extractor_model/predefined_extractors.md index 7929adf..6bd5efb 100644 --- a/docs/3-extractor_model/predefined_extractors.md +++ b/docs/3-extractor_model/predefined_extractors.md @@ -48,13 +48,13 @@ specifying how to reach and operate the Kafka stream, specifically: There are plenty of additional settings, the main ones being: -- server: +- _server_: - Hostname or IP address of the Kafka server broadcasting data. - Defaults to `localhost`. -- port: +- _port_: - Port from which the server is broadcasting data. - Defaults to `9092`. -- groupId: +- _groupId_: - Group to which the underlying Kafka consumer belongs - Defaults to an autogenerated group ID with the app's name and version. diff --git a/docs/4-error_handling/predefined_errors.md b/docs/4-error_handling/predefined_errors.md index 27e9e5b..0915303 100644 --- a/docs/4-error_handling/predefined_errors.md +++ b/docs/4-error_handling/predefined_errors.md @@ -6,7 +6,7 @@ title: Pre-defined errors # Pre-defined errors @APP_NAME@ has some built-in exception types that are thrown on some common -error that might arise during the validation flow. +errors that might arise during the validation flow. ## Stream exceptions @@ -24,16 +24,12 @@ configuration: Thrown when the processing of an item threw an error and the validator was configured to halt on errors. Contains the original error cause. -> See [org.ragna.comet.exception.stream.validations](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/exception/stream/validations.html) - ### Timed - [StreamTimeoutException](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/exception/stream/timed/StreamTimeoutException.html): Thrown when the validation stream was not fed any data for a time period longer than the extractor's configured timeout. -> See [org.ragna.comet.exception.stream.timed](https://ulitol97.github.io/comet/scaladoc/org/ragna/comet/exception/stream/timed.html) - ## Configuration exceptions - [IllegalArgumentException](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/IllegalArgumentException.html): diff --git a/docs/5-testing_auditing/logging.md b/docs/5-testing_auditing/logging.md index 958dcfe..907d0ca 100644 --- a/docs/5-testing_auditing/logging.md +++ b/docs/5-testing_auditing/logging.md @@ -13,12 +13,13 @@ For this purpose, [scala-logging](https://github.com/lightbend/scala-logging) has been used for several reasons: 1. It just provides a logging **front-end**, meaning the parent project is in charge of defining a logging mechanism and configuration, -which will be honored by @APP_INNER_NAME@. +which will be honored by @APP_NAME@. 2. It is a Scala wrapper for the [SLF4J](https://www.slf4j.org/), a mature and reliable Java logging framework. 3. Provides several macros and utilities to reduce the verbosity of the code -in charge logging messages. Take for example: -```scala +in charge of logging messages. + +```scala title="Code example using scala-logging" // 1. Extend LazyLogging object Main extends IOApp with LazyLogging { override def run(args: List[String]): IO[ExitCode] = { diff --git a/docs/5-testing_auditing/unit-tests.md b/docs/5-testing_auditing/unit-tests.md index 22fbd95..b911fa3 100644 --- a/docs/5-testing_auditing/unit-tests.md +++ b/docs/5-testing_auditing/unit-tests.md @@ -10,7 +10,7 @@ title: Unit tests - [scalatest](https://www.scalatest.org/): an extensible, widely adopted scala testing framework. - [cats-effect-testing](https://github.com/typelevel/cats-effect-testing): - Typelevel's compatibility layer between cats-effect and tests frameworks + Typelevel's compatibility layer between cats-effect and tests frameworks. You may run the tests by running `sbt test` or simply `test` from the SBT shell. @@ -30,17 +30,17 @@ Test the working of the validators in different scenarios. 1. RDF data is generated in all accepted formats. 2. Validation schemas are generated in all accepted engines and formats. 3. All combinations are used to perform validations, testing that the - validation output is correct + validation output is correct. ### Halting - Goals: - Ensure that @APP_NAME@'s validation stream halts when configured to do so - for either invalid or erroring validations + for either invalid or erroring validations. - Modus operandi: - 1. Well formatted and badly formatted RDF data is generated - 2. Validation schemas that won't validate the data are generated + 1. Well formatted and badly formatted RDF data is generated. + 2. Validation schemas that won't validate the data are generated. 3. The data is validated against the schemas, checking that the correct error is thrown for each situation. @@ -51,8 +51,8 @@ Test the working of the validators in different scenarios. extractor timeout when no items are received after some time - Modus operandi: - 1. A trivial validator is run with an unfeasible timeout - 2. Check that a timeout error is thrown when the validator is initiated + 1. A trivial validator is run with an unfeasible timeout. + 2. Check that a timeout error is thrown when the validator is initiated. ## Extractor tests @@ -62,5 +62,5 @@ Test the working of the validators in different scenarios. - Modus operandi: 1. Some trivial but valid RDF/Schema combinations are produced and then - consumed by a validator, but each time the validator will be fed through a + consumed by a validator. Each time, the validator will be fed through a different extractor to make sure all extractors work the same. \ No newline at end of file