From 5f6949b9165a08a38662ae6733b58958e79d068b Mon Sep 17 00:00:00 2001 From: Martin Nonnenmacher Date: Thu, 14 Sep 2023 22:17:50 +0200 Subject: [PATCH] docs: Fix all links in Docusaurus Fix all Markdown links and configure the Docusaurus build to fail on broken links. Compared to before there are two main differences for links within Docusuaurus: * Links between URL links need to be URL links to be resolved. This will be fixed in Docusaurus 3 [1]. * Links that point to files outside the "docusaurus" directory need to be absolute links to be resolvable in the final website. This could mabye be improved by adding support for variables [2]. [1]: https://github.com/facebook/docusaurus/issues/6370 [2]: https://github.com/facebook/Docusaurus/issues/395 Signed-off-by: Martin Nonnenmacher --- .../docs/configuration/copyright-garbage.md | 3 +- .../docs/configuration/evaluator-rules.md | 5 +-- .../configuration/license-classifications.md | 10 ++--- .../docs/configuration/license-texts.md | 2 +- docusaurus/docs/configuration/ort-yml.md | 34 +++++++------- .../configuration/package-configurations.md | 6 +-- .../docs/configuration/package-curations.md | 13 +++--- docusaurus/docs/configuration/resolutions.md | 14 +++--- .../docs/getting-started/installation.md | 2 +- docusaurus/docs/getting-started/usage.md | 45 ++++++++++--------- docusaurus/docs/guides/license-handling.md | 12 ++--- docusaurus/docs/guides/sw360-integration.md | 9 ++-- docusaurus/docs/license.md | 4 +- docusaurus/docs/tools/advisor.md | 8 ++-- docusaurus/docs/tools/analyzer.md | 5 +-- docusaurus/docs/tools/downloader.md | 5 ++- docusaurus/docs/tools/evaluator.md | 2 +- docusaurus/docs/tools/reporter.md | 5 ++- docusaurus/docs/tools/scanner.md | 15 ++++--- docusaurus/docusaurus.config.js | 2 +- docusaurus/tutorial/intro.md | 32 ++++++------- 21 files changed, 119 insertions(+), 114 deletions(-) diff --git a/docusaurus/docs/configuration/copyright-garbage.md b/docusaurus/docs/configuration/copyright-garbage.md index a964739d4c42..b6a7932ed069 100644 --- a/docusaurus/docs/configuration/copyright-garbage.md +++ b/docusaurus/docs/configuration/copyright-garbage.md @@ -2,8 +2,7 @@ The `copyright-garbage.yml` file allows to define which Copyright statements are to be considered as garbage, like any invalid findings from a scanner. This can be done by literal strings or regular expression patterns. The *evaluator* and -*reporter* take the file as optional input. See the [copyright-garbage.yml example](../examples/copyright-garbage.yml) -as a base to get started. +*reporter* take the file as optional input. See the [example](#example) as a base to get started. ## Command Line diff --git a/docusaurus/docs/configuration/evaluator-rules.md b/docusaurus/docs/configuration/evaluator-rules.md index a34f2fcd19dc..b24a88b3144a 100644 --- a/docusaurus/docs/configuration/evaluator-rules.md +++ b/docusaurus/docs/configuration/evaluator-rules.md @@ -6,10 +6,9 @@ findings. Rules are written in a Kotlin-based DSL. For each policy rule violation, you can define 'How to fix' follow-up actions to help users resolve policy rules violations by themselves. -You can use the [example rules](../../examples/example.rules.kts) as the base script file for your policy rules. Note +You can use the [example rules](#example) as the base script file for your policy rules. Note that this example depends on the license categorizations defined in the -[license-classifications example](../../examples/license-classifications.yml), see the -[license-classifications docs](../config-file-license-classifications-yml.md). +[license-classifications example](license-classifications.md#example). ## Command Line diff --git a/docusaurus/docs/configuration/license-classifications.md b/docusaurus/docs/configuration/license-classifications.md index 111d0404061e..0b98e72569b6 100644 --- a/docusaurus/docs/configuration/license-classifications.md +++ b/docusaurus/docs/configuration/license-classifications.md @@ -2,7 +2,7 @@ The `license-classifications.yml` file holds a user-defined categorization of licenses. -You can use the [license-classifications.yml example] as the base configuration +You can use the [example](#example) as the base configuration file for your scans. The file consists of two sections: The first one, *categories*, allows defining arbitrary categories for grouping @@ -26,7 +26,7 @@ The information from the `license-classifications.yml` is evaluated by the follo decide, which licenses to include into the generated notice file. The [license-classifications.yml example] demonstrates the intended use cases. It defines some categories that specify -whether licenses are applicable to development projects. The [example.rules.kts] checks ORT results against these +whether licenses are applicable to development projects. The [example](#example) checks ORT results against these categories and generates issues if the rules detect a misuse. In addition, there are some other categories to be evaluated by the templates for the notice file: The @@ -52,12 +52,10 @@ cli/build/install/ort/bin/ort evaluate --rules-file $ORT_CONFIG_DIR/evaluator.rules.kts ``` -[license-classifications.yml example]: ../examples/license-classifications.yml [generated license-classifications.yml]: https://github.com/maxhbr/LDBcollector/blob/generated/ort/license-classifications.yml [LDBcollector]: https://github.com/maxhbr/LDBcollector -[Rules]: scripts/rules-kts.md -[Plain text templates]: reporters/plain-text-templates.md -[example.rules.kts]: ../examples/example.rules.kts +[Rules]: evaluator-rules.md +[Plain text templates]: reporter-templates.md#plain-text-templates ## Example diff --git a/docusaurus/docs/configuration/license-texts.md b/docusaurus/docs/configuration/license-texts.md index bd57f6aab052..fe1545e54e22 100644 --- a/docusaurus/docs/configuration/license-texts.md +++ b/docusaurus/docs/configuration/license-texts.md @@ -3,7 +3,7 @@ ORT does provide the license texts for all [SPDX licenses](https://spdx.org/licenses/) and for all license references from [ScanCode](https://github.com/nexB/scancode-toolkit/tree/develop/src/licensedcode/data/licenses). These license texts will be used when generating open source notices using the -[PlainTextTemplateReporter](reporters/plain-text-templates.md). +[PlainTextTemplateReporter](reporter-templates.md#plain-text-templates). If you need a license text that is not provided by ORT you can put it in the custom license texts directory. By default, it is located at `$ORT_CONFIG_DIR/custom-license-texts`. Alternatively, you can pass a different location to the diff --git a/docusaurus/docs/configuration/ort-yml.md b/docusaurus/docs/configuration/ort-yml.md index 347533ee3eb1..494624ec2deb 100644 --- a/docusaurus/docs/configuration/ort-yml.md +++ b/docusaurus/docs/configuration/ort-yml.md @@ -10,8 +10,8 @@ increased degree of automation and local configurations should only be done if t * [resolutions](#resolutions) - Resolve any issues or policy rule violations. * [license choices](#license-choices) - Select a license for packages which offer a license choice. -The sections below explain each in further detail. Prefer to learn by example? See the [.ort.yml](../.ort.yml) for the -OSS Review Toolkit itself. +The sections below explain each in further detail. Prefer to learn by example? See the +[.ort.yml](https://github.com/oss-review-toolkit/ort/blob/main/.ort.yml) for the OSS Review Toolkit itself. ## Excludes @@ -75,7 +75,7 @@ excludes: ``` Where the list of available options for `reason` is defined in -[PathExcludeReason.kt](../model/src/main/kotlin/config/PathExcludeReason.kt). For how to write a glob pattern, please +[PathExcludeReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/PathExcludeReason.kt). For how to write a glob pattern, please see the [AntPathMatcher documentation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html). @@ -83,7 +83,7 @@ The path exclude above has the following effects: * All projects found below the `test-data` directory are marked as excluded. * License findings in files below the `test-data` directory are marked as excluded. This can be used in - [evaluator rules](getting-started.md#6-running-the-evaluator) to for instance change the severity from error to + [evaluator rules](../../tutorial/intro#6-running-the-evaluator) to for instance change the severity from error to warning. ```yaml @@ -118,7 +118,7 @@ The above example excludes all the following scopes for all projects: `testAnnot `testRuntimeOnly`. Where the list of available options for scopes is defined in -[ScopeExcludeReason.kt](../model/src/main/kotlin/config/ScopeExcludeReason.kt). +[ScopeExcludeReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/ScopeExcludeReason.kt). See the examples below for typical scope excludes for the supported package managers. Note that you must verify that the scopes defined in the examples below match the scopes in your project. @@ -164,7 +164,7 @@ import Yarn from '!!raw-loader!@site/../examples/yarn.ort.yml' License finding curations should be used when you want to correct the licenses detected in the source code of the project. To define curations on global level for third-party packages, please use -[curations](config-file-curations-yml.md) or [package configurations](config-file-package-configuration-yml.md). +[curations](package-curations.md) or [package configurations](package-configurations.md). ### Curating Project License Findings @@ -189,7 +189,7 @@ curations: To correct identified licenses in a dependency you can use a package configuration to overwrite scanner findings. Note that this feature requires `enableRepositoryPackageConfigurations` to be enabled in the -[config.yml](../README.md#ort-configuration-file). +[config.yml](../getting-started/usage.md#ort-configuration-file). ```yaml package_configurations: @@ -206,9 +206,9 @@ package_configurations: ``` For details of the specification, see -[LicenseFindingCuration.kt](../model/src/main/kotlin/config/LicenseFindingCuration.kt). +[LicenseFindingCuration.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCuration.kt). The list of available options for `reason` are defined in -[LicenseFindingCurationReason.kt](../model/src/main/kotlin/config/LicenseFindingCurationReason.kt). +[LicenseFindingCurationReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/LicenseFindingCurationReason.kt). ### Curating Metadata @@ -216,7 +216,7 @@ Package curations can be added if you want to correct metadata of third-party de The following example corrects the source-artifact URL of the package with the id `Maven:com.example:dummy:0.0.1`. Note that this feature requires `enableRepositoryPackageCurations` to be enabled in the -[config.yml](../README.md#ort-configuration-file). +[config.yml](../getting-started/usage.md#ort-configuration-file). ```yaml curations: @@ -229,7 +229,7 @@ curations: ``` For more information about package curations see -[the documentation for the curations.yml file](config-file-curations-yml.md). +[the documentation for the curations.yml file](package-curations.md). ### Example @@ -245,7 +245,7 @@ import Curations from '!!raw-loader!@site/../examples/curations.ort.yml' Resolutions should be used if you are unable to solve an issue by other means. -If a resolution is not project-specific than add it to [resolutions.yml](./config-file-resolutions-yml.md) so that it is +If a resolution is not project-specific than add it to [resolutions.yml](resolutions.md) so that it is applied to each scan. ### Resolution Basics @@ -280,7 +280,7 @@ resolutions: ``` Where the list of available options for `reason` is defined in -[IssueResolutionReason.kt](../model/src/main/kotlin/config/IssueResolutionReason.kt) +[IssueResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/IssueResolutionReason.kt) For example, to ignore an issue related to a build tool problem, your `.ort.yml` could include: @@ -297,7 +297,7 @@ resolutions: Resolutions should not be used to resolve license policy rule violations as they do not change the generated open source notices. To resolve a license policy rule violation either add a [license finding curation](#curations) to the .ort.yml file if the finding is in your code repository or add a curation to the -[curations.yml](config-file-curations-yml.md) if the violation occurs in a third-party dependency. +[curations.yml](package-curations.md) if the violation occurs in a third-party dependency. The code below shows the structure of a policy rule violation resolution in the `.ort.yml` file: @@ -310,7 +310,7 @@ resolutions: ``` Where the list of available options for `reason` is defined in -[RuleViolationResolutionReason.kt](../model/src/main/kotlin/config/RuleViolationResolutionReason.kt). +[RuleViolationResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/RuleViolationResolutionReason.kt). For example, to confirm you acquired a commercial Qt license for your project, your `.ort.yml` could include: @@ -335,7 +335,7 @@ resolutions: ``` Where the list of available options for `reason` is defined in -[VulnerabilityResolutionReason.kt](../model/src/main/kotlin/config/VulnerabilityResolutionReason.kt). +[VulnerabilityResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/VulnerabilityResolutionReason.kt). For example, to ignore a vulnerability that is ineffective, because it is not invoked in your project, your `.ort.yml` could include: @@ -363,7 +363,7 @@ import Resolutions from '!!raw-loader!@site/../examples/resolutions.ort.yml' For multi-licensed dependencies a specific license can be selected. The license choice can be applied to a package or globally to an SPDX expression in the project. A choice is only valid for licenses combined with the SPDX operator `OR`. The choices are applied in the evaluator, and the reporter to the effective license of a package, which is calculated by -the chosen [LicenseView](../model/src/main/kotlin/licenses/LicenseView.kt). +the chosen [LicenseView](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/licenses/LicenseView.kt). ### License Choice by Package diff --git a/docusaurus/docs/configuration/package-configurations.md b/docusaurus/docs/configuration/package-configurations.md index e13d5ac9a599..059193ce2f24 100644 --- a/docusaurus/docs/configuration/package-configurations.md +++ b/docusaurus/docs/configuration/package-configurations.md @@ -2,7 +2,7 @@ A package configuration file allows you to define path excludes and license finding curations for a specific package (dependency) and provenance. Conceptually, the file is similar to -[.ort.yml](https://github.com/oss-review-toolkit/ort/blob/main/docs/config-file-ort-yml.md), but it is used only for +[.ort.yml](ort-yml.md), but it is used only for packages included via a package manager as project dependencies, and not for the project's own source code repository to be scanned. @@ -44,8 +44,8 @@ in the source repository but only used for building, documenting or testing the to fix incorrect scan results, for example if a wrong license was detected, or if a finding is a false positive. The entries for path excludes and license finding curations have the same syntax and semantics as in the `ort.yml` file, -see [excluding paths](config-file-ort-yml.md#excluding-paths) and -[curating license findings](config-file-ort-yml.md#curating-project-license-findings) for details. +see [excluding paths](ort-yml.md#excluding-paths) and +[curating license findings](ort-yml.md#curating-project-license-findings) for details. ```yaml id: "Pip::example-package:0.0.1" diff --git a/docusaurus/docs/configuration/package-curations.md b/docusaurus/docs/configuration/package-curations.md index 9d6d0b132deb..ad8c2bb5cec9 100644 --- a/docusaurus/docs/configuration/package-curations.md +++ b/docusaurus/docs/configuration/package-curations.md @@ -2,7 +2,7 @@ Curations correct invalid or missing package metadata and set the concluded license for packages. -You can use the [curations.yml example](../examples/curations.yml) as the base configuration file for your scans. +You can use the [curations.yml example](#example) as the base configuration file for your scans. ## When to Use Curations @@ -33,7 +33,7 @@ Curations can be used to: The sections below explain how to create curations in the `curations.yml` file which, if passed to the *analyzer*, is applied to all package metadata found in the analysis. If a license detected in the source code of a package needs to be corrected, add -a license finding curation in the [.ort.yml](config-file-ort-yml.md#curations) file for the project. +a license finding curation in the [.ort.yml](ort-yml.md#curations) file for the project. ## Curations Basics @@ -48,7 +48,7 @@ location of source artifacts. Hint: If the `concluded_license` *and* the `authors` are curated, this package will be skipped during the `scan` step, as no more information from the scanner is required. This requires the `skipConcluded` scanner option to be enabled in -the [config.yml](../README.md#ort-configuration-file). +the [config.yml](../getting-started/usage.md#ort-configuration-file). The structure of the curations file consist of one or more `id` entries: @@ -83,7 +83,7 @@ The structure of the curations file consist of one or more `id` entries: ``` Where the list of available options for curations is defined in -[PackageCurationData.kt](../model/src/main/kotlin/PackageCurationData.kt). +[PackageCurationData.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/PackageCurationData.kt). ## Command Line @@ -98,10 +98,11 @@ cli/build/install/ort/bin/ort analyze Alternatively to a single file, curations may also be split across multiple files below a directory, by default `$ORT_CONFIG_DIR/curations`. File and directory package curation providers may also be configured as -[FilePackageCurationProviders](../plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt) +[FilePackageCurationProviders](https://github.com/oss-review-toolkit/ort/blob/main/plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt) in `$ORT_CONFIG_DIR/config.yml`. Similarly, ORT can use [ClearlyDefined](https://clearlydefined.io/) and [SW360](https://www.eclipse.org/sw360/) as sources for curated metadata. See the -[reference configuration file](../model/src/main/resources/reference.yml) for examples. +[reference configuration file](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml) +for examples. To override curations, e.g. for testing them locally, you can also pass a `curations.yml` file or a curations directory via the `--package-curations-file` / `--package-curations-dir` options of the *evaluator*: diff --git a/docusaurus/docs/configuration/resolutions.md b/docusaurus/docs/configuration/resolutions.md index e76934c7d265..c06002e15a60 100644 --- a/docusaurus/docs/configuration/resolutions.md +++ b/docusaurus/docs/configuration/resolutions.md @@ -3,7 +3,7 @@ Resolutions allow you to *resolve* issues, policy rule violations or vulnerabilities by providing a reason why they are acceptable and can be ignored. -You can use the [resolutions.yml example](../examples/resolutions.yml) as the base configuration file for your scans. +You can use the [resolutions.yml example](#example) as the base configuration file for your scans. ## When to Use Resolutions @@ -11,7 +11,7 @@ Resolutions should be used when it is impossible to solve an issue or a fix is p The sections below explain how to create resolutions in the `resolutions.yml` file which, if passed as an argument to the *reporter*, applies to each scan made. If a resolution is project-specific, then add it in the -[.ort.yml](config-file-ort-yml.md) file for the project. +[.ort.yml](ort-yml.md) file for the project. Resolutions are only taken into account by the *reporter*, while the *analyzer* and *scanner* ignore them. @@ -45,7 +45,7 @@ issues: ``` Where the list of available options for `reason` is defined in -[IssueResolutionReason.kt](../model/src/main/kotlin/config/IssueResolutionReason.kt). +[IssueResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/IssueResolutionReason.kt). For example, to ignore an issue related to a build tool problem, your `resolutions.yml` could include: @@ -60,8 +60,8 @@ issues: Resolutions should not be used to resolve license policy rule violations as they do not the change generated open source notices. To resolve a license policy rule violation either add a local `license_findings` curation to the -[.ort.yml file](./config-file-ort-yml.md) if the finding is in your code repository or add a curation to the -[curations.yml](config-file-curations-yml.md) if the violation occurs in a third-party dependency. +[.ort.yml file](./ort-yml.md) if the finding is in your code repository or add a curation to the +[curations.yml](package-curations.md) if the violation occurs in a third-party dependency. The code below shows the structure of a policy rule violation resolution in the `resolutions.yml` file: @@ -73,7 +73,7 @@ rule_violations: ``` Where the list of available options for `reason` is defined in -[RuleViolationResolutionReason.kt](../model/src/main/kotlin/config/RuleViolationResolutionReason.kt). +[RuleViolationResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/RuleViolationResolutionReason.kt). For example, to confirm your organization has acquired an org-wide Qt commercial license, your `resolutions.yml` could include: @@ -97,7 +97,7 @@ vulnerabilities: ``` Where the list of available options for `reason` is defined in -[VulnerabilityResolutionReason.kt](../model/src/main/kotlin/config/VulnerabilityResolutionReason.kt). +[VulnerabilityResolutionReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/VulnerabilityResolutionReason.kt). For example, to ignore a vulnerability that is ineffective, because it is not invoked in your project, your `resolutions.yml` could include: diff --git a/docusaurus/docs/getting-started/installation.md b/docusaurus/docs/getting-started/installation.md index 0169c38f7b62..9e833ddfdb1b 100644 --- a/docusaurus/docs/getting-started/installation.md +++ b/docusaurus/docs/getting-started/installation.md @@ -51,7 +51,7 @@ Depending on how ORT was installed, it can be run in the following ways: docker run ort --help ``` - You can find further hints for using ORT with Docker in the [documentation](./docs/hints-for-use-with-docker.md). + You can find further hints for using ORT with Docker in the [documentation](../guides/docker.md). * If the ORT distribution was built from sources, use diff --git a/docusaurus/docs/getting-started/usage.md b/docusaurus/docs/getting-started/usage.md index f1e402e951c7..ef1193449301 100644 --- a/docusaurus/docs/getting-started/usage.md +++ b/docusaurus/docs/getting-started/usage.md @@ -22,16 +22,18 @@ ort --info analyze -f JSON -i /project -o /project/ort/analyzer Just the like top-level `ort` command, the subcommands for all tools provide a `--help` option for detailed usage help. Use it like `ort analyze --help`. -Please see [Getting Started](./docs/getting-started.md) for an introduction to the individual tools. +Please see [Getting Started](../../tutorial/intro) for an introduction to the individual tools. ## Running on CI A basic ORT pipeline (using the *analyzer*, *scanner* and *reporter*) can easily be run on -[Jenkins CI](https://jenkins.io/) by using the [Jenkinsfile](./integrations/jenkins/Jenkinsfile) in a (declarative) -[pipeline](https://jenkins.io/doc/book/pipeline/) job. Please see the [Jenkinsfile](./integrations/jenkins/Jenkinsfile) -itself for documentation of the required Jenkins plugins. The job accepts various parameters that are translated to ORT -command line arguments. Additionally, one can trigger a downstream job which e.g. further processes scan results. Note -that it is the downstream job's responsibility to copy any artifacts it needs from the upstream job. +[Jenkins CI](https://jenkins.io/) by using the +[Jenkinsfile](https://github.com/oss-review-toolkit/ort/blob/main/integrations/jenkins/Jenkinsfile) in a (declarative) +[pipeline](https://jenkins.io/doc/book/pipeline/) job. Please see the +[Jenkinsfile](https://github.com/oss-review-toolkit/ort/blob/main/integrations/jenkins/Jenkinsfile) itself for +documentation of the required Jenkins plugins. The job accepts various parameters that are translated to ORT command +line arguments. Additionally, one can trigger a downstream job which e.g. further processes scan results. Note that it +is the downstream job's responsibility to copy any artifacts it needs from the upstream job. ## Configuration @@ -56,7 +58,7 @@ environment variable, which in turn defaults to the `.ort` directory below the c The following provides an overview of the various configuration files that can be used to customize ORT behavior: -#### [ORT configuration file](./model/src/main/resources/reference.yml) +#### [ORT configuration file](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml) The main configuration file for the operation of ORT. This configuration is maintained by an administrator who manages the ORT instance. In contrast to the configuration files in the following, this file rarely changes once ORT is @@ -66,9 +68,10 @@ operational. |--------|--------|------------------------------| | YAML | Global | `$ORT_CONFIG_DIR/config.yml` | -The [reference configuration file](./model/src/main/resources/reference.yml) gives a good impression about the content -of the main ORT configuration file. It consists of sections related to different subcomponents of ORT. The meaning -of these sections and the properties they can contain is described together with the corresponding subcomponents. +The [reference configuration file](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml) +gives a good impression about the content of the main ORT configuration file. It consists of sections related to +different subcomponents of ORT. The meaning of these sections and the properties they can contain is described together +with the corresponding subcomponents. While the file is rather static, there are means to override configuration options for a specific run of ORT or to customize the configuration to a specific environment. The following options are supported, in order of precedence: @@ -102,7 +105,7 @@ To print the active configuration use: ort config --show-active ``` -#### [Copyright garbage file](./docs/config-file-copyright-garbage-yml.md) +#### [Copyright garbage file](../configuration/copyright-garbage.md) A list of copyright statements that are considered garbage, for example statements that were incorrectly classified as copyrights by the scanner. @@ -111,7 +114,7 @@ copyrights by the scanner. |-------------|--------|-----------------------------------------| | YAML / JSON | Global | `$ORT_CONFIG_DIR/copyright-garbage.yml` | -#### [Curations file](./docs/config-file-curations-yml.md) +#### [Curations file](../configuration/package-curations.md) A file to correct invalid or missing package metadata, and to set the concluded license for packages. @@ -119,7 +122,7 @@ A file to correct invalid or missing package metadata, and to set the concluded |-------------|--------|---------------------------------| | YAML / JSON | Global | `$ORT_CONFIG_DIR/curations.yml` | -#### [Custom license texts dir](./docs/dir-custom-license-texts.md) +#### [Custom license texts dir](../configuration/license-texts.md) A directory that contains license texts which are not provided by ORT. @@ -127,7 +130,7 @@ A directory that contains license texts which are not provided by ORT. |--------|--------|-----------------------------------------| | Text | Global | `$ORT_CONFIG_DIR/custom-license-texts/` | -#### [How to fix text provider script](./docs/scripts/how-to-fix-text-provider-kts.md) +#### [How to fix text provider script](../configuration/how-to-fix-text-provider.md) A Kotlin script that enables the injection of how-to-fix texts in Markdown format for ORT issues into the reports. @@ -135,7 +138,7 @@ A Kotlin script that enables the injection of how-to-fix texts in Markdown forma |---------------|--------|---------------------------------------------------------| | Kotlin script | Global | `$ORT_CONFIG_DIR/reporter.how-to-fix-text-provider.kts` | -#### [License classifications file](docs/config-file-license-classifications-yml.md) +#### [License classifications file](../configuration/license-classifications.md) A file that contains user-defined categorization of licenses. @@ -143,7 +146,7 @@ A file that contains user-defined categorization of licenses. |-------------|--------|-----------------------------------------------| | YAML / JSON | Global | `$ORT_CONFIG_DIR/license-classifications.yml` | -#### [Resolution file](./docs/config-file-resolutions-yml.md) +#### [Resolution file](../configuration/resolutions.md) Configurations to resolve any issues or rule violations by providing a mandatory reason, and an optional comment to justify the resolution on a global scale. @@ -152,7 +155,7 @@ justify the resolution on a global scale. |-------------|--------|-----------------------------------| | YAML / JSON | Global | `$ORT_CONFIG_DIR/resolutions.yml` | -#### [Repository configuration file](./docs/config-file-ort-yml.md) +#### [Repository configuration file](../configuration/ort-yml.md) A configuration file, usually stored in the project's repository, for license finding curations, exclusions, and issues or rule violations resolutions in the context of the repository. @@ -161,18 +164,18 @@ or rule violations resolutions in the context of the repository. |-------------|----------------------|---------------------------------| | YAML / JSON | Repository (project) | `[analyzer-input-dir]/.ort.yml` | -#### [Package configuration file / directory](./docs/config-file-package-configuration-yml.md) +#### [Package configuration file / directory](../configuration/package-configurations.md) A single file or a directory with multiple files containing configurations to set provenance-specific path excludes and license finding curations for dependency packages to address issues found within a scan result. `helper-cli`'s -[`package-config create` command](./helper-cli/src/main/kotlin/commands/packageconfig/CreateCommand.kt) +[`package-config create` command](https://github.com/oss-review-toolkit/ort/blob/main/helper-cli/src/main/kotlin/commands/packageconfig/CreateCommand.kt) can be used to populate a directory with template package configuration files. | Format | Scope | Default location | |-------------|----------------------|-------------------------------------------| | YAML / JSON | Package (dependency) | `$ORT_CONFIG_DIR/package-configurations/` | -#### [Policy rules file](./docs/scripts/rules-kts.md) +#### [Policy rules file](../configuration/evaluator-rules.md) The file containing any policy rule implementations to be used with the *evaluator*. @@ -191,7 +194,7 @@ default propagated to the child processes spawned by it. To reduce this risk, ORT filters out certain environment variables when it runs external tools in child processes. This filter mechanism can be configured via the following properties in the -[ORT configuration file](./model/src/main/resources/reference.yml): +[ORT configuration file](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml): | Property | Description | |----------|-------------| diff --git a/docusaurus/docs/guides/license-handling.md b/docusaurus/docs/guides/license-handling.md index 4c6d920aebd2..8a1470b7c663 100644 --- a/docusaurus/docs/guides/license-handling.md +++ b/docusaurus/docs/guides/license-handling.md @@ -17,9 +17,9 @@ package might have declared itself to be licensed under the MIT license, but in BSD-3-Clause license header. Declared licenses often come in non-SPDX form or contains typos. For universally valid cases ORT has built-in -[mappings](../utils/spdx/src/main/resources/declared-license-mapping.yml). For cases that might be ambiguous in general -but are valid in the specific context of a package, [curations](config-file-curations-yml.md) can be used to define a -`declared_license_mapping`. +[mappings](https://github.com/oss-review-toolkit/ort/blob/main/utils/spdx/src/main/resources/declared-license-mapping.yml). +For cases that might be ambiguous in general but are valid in the specific context of a package, +[curations](../configuration/package-curations.md) can be used to define a `declared_license_mapping`. ### Detected license @@ -30,7 +30,7 @@ where the declared and detected licenses do not match. ### Concluded license -The concluded license is manually created via a [curation](config-file-curations-yml.md). In cases where the union of +The concluded license is manually created via a [curation](../configuration/package-curations.md). In cases where the union of declared and detected licenses is wrong (e.g. due to mistakes in metadata or false positives from scanners), the concluded license can be used to set which licenses actually match reality. Curating a concluded license should be an objective decision based on verifiable facts. It should not yet apply a license choice, as it is the complete license @@ -39,7 +39,7 @@ expression a package can theoretically be used under. ### Effective license The effective license finally is the one that takes effect for the package, taking into account any project-specific -context like making a [license choice](config-file-ort-yml.md#license-choices) in case of dual-licensing. This is the +context like making a [license choice](../configuration/ort-yml.md#license-choices) in case of dual-licensing. This is the license that should primarily be used in ORT's *evaluator* rules. ## Curating licenses @@ -50,7 +50,7 @@ versions of a package: There is a risk that a newer package version introduces n with a concluded license that blindly overrides everything. That is why in such scenarios a -[license finding curation](config-file-package-configuration-yml.md#defining-path-excludes-and-license-finding-curations) +[license finding curation](../configuration/package-configurations.md#defining-path-excludes-and-license-finding-curations) as part of a package configuration is the better option, as it allows to conclude a single exact finding of a license. That way unmatched licenses are not affected by the curation and new / changed licenses will not go unnoticed. diff --git a/docusaurus/docs/guides/sw360-integration.md b/docusaurus/docs/guides/sw360-integration.md index ee6d776d50bc..dbc1c2a206c7 100644 --- a/docusaurus/docs/guides/sw360-integration.md +++ b/docusaurus/docs/guides/sw360-integration.md @@ -19,7 +19,7 @@ To add packages found by ORT to projects and releases in SW360. In order to be able to upload ORT results to SW360, first set the connection parameters to your SW360 instance. You can do this by defining a `sw360Configuration` scanner storage in the `storages` section of your -[config.yml](../README.md#ort-configuration-file) (e.g. in `${HOME}/.ort/conf`) or pass it to the ORT command with the +[config.yml](../getting-started/usage.md#ort-configuration-file) (e.g. in `${HOME}/.ort/conf`) or pass it to the ORT command with the `--config` option as shown below. ```yaml @@ -39,7 +39,8 @@ ort: ### Command Line Uploading to SW360 is a stand-alone -[ORT command](../plugins/commands/upload-result-to-sw360/src/main/kotlin/UploadResultToSw360Command.kt), which: +[ORT command](https://github.com/oss-review-toolkit/ort/blob/main/plugins/commands/upload-result-to-sw360/src/main/kotlin/UploadResultToSw360Command.kt), +which: 1. Takes an *analyzer* result file as an input, 2. Creates components/releases in SW360 for the packages and ... @@ -55,7 +56,7 @@ cli/build/install/ort/bin/ort upload-result-to-sw360 ### When to use If you prefer to use the SW360 web frontend to correct package metadata instead of ORT's -[curations.yml file](config-file-curations-yml.md). +[curations.yml file](../configuration/package-curations.md). Note: @@ -67,7 +68,7 @@ Note: In order to be able to use SW360 data in the ORT *analyzer*, first set the connection parameters for your SW360 instance. You can do this by defining a `sw360Configuration` within the `analyzer` section of your -[config.yml](../README.md#ort-configuration-file) (e.g. in `${HOME}/.ort/conf`) or pass it to the ORT command with the +[config.yml](../getting-started/usage.md#ort-configuration-file) (e.g. in `${HOME}/.ort/conf`) or pass it to the ORT command with the `--config` option as shown below. ```yaml diff --git a/docusaurus/docs/license.md b/docusaurus/docs/license.md index 2719e6646b89..177c0b315483 100644 --- a/docusaurus/docs/license.md +++ b/docusaurus/docs/license.md @@ -4,9 +4,9 @@ sidebar_position: 8 # License -Copyright (C) 2017-2023 [The ORT Project Authors](./NOTICE). +Copyright (C) 2017-2023 [The ORT Project Authors](https://github.com/oss-review-toolkit/ort/blob/main/NOTICE). -See the [LICENSE](./LICENSE) file in the root of this project for license details. +See the [LICENSE](https://github.com/oss-review-toolkit/ort/blob/main/LICENSE) file in the root of this project for license details. OSS Review Toolkit (ORT) is a [Linux Foundation project](https://www.linuxfoundation.org) and part of [ACT](https://automatecompliance.org/). diff --git a/docusaurus/docs/tools/advisor.md b/docusaurus/docs/tools/advisor.md index 94dae00add90..dfdf33d22842 100644 --- a/docusaurus/docs/tools/advisor.md +++ b/docusaurus/docs/tools/advisor.md @@ -10,10 +10,10 @@ vulnerabilities returned by these services are then stored in the output result information like the source of the data and a severity (if available). Multiple providers for security advisories are available. The providers require specific configuration in the -[ORT configuration file](./model/src/main/resources/reference.yml), which needs to be placed in the *advisor* -section. When executing the advisor the providers to enable are selected with the `--advisors` option (or its short -alias `-a`); here a comma-separated list with provider IDs is expected. The following sections describe the providers -supported by the advisor: +[ORT configuration file](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml), +which needs to be placed in the *advisor* section. When executing the advisor the providers to enable are selected with +the `--advisors` option (or its short alias `-a`); here a comma-separated list with provider IDs is expected. The +following sections describe the providers supported by the advisor: ## NexusIQ diff --git a/docusaurus/docs/tools/analyzer.md b/docusaurus/docs/tools/analyzer.md index 31ccd703f242..c4a494085b88 100644 --- a/docusaurus/docs/tools/analyzer.md +++ b/docusaurus/docs/tools/analyzer.md @@ -74,6 +74,5 @@ supported: If another package manager that is not part of the list above is used (or no package manager at all), the generic fallback to [SPDX documents](https://spdx.dev/specifications/) can be leveraged to describe -[projects](./plugins/package-managers/spdx/src/funTest/assets/projects/synthetic/inline-packages/project-xyz.spdx.yml) -or [packages](./plugins/package-managers/spdx/src/funTest/assets/projects/synthetic/libs/curl/package.spdx.yml). - +[projects](https://github.com/oss-review-toolkit/ort/blob/main/plugins/package-managers/spdx/src/funTest/assets/projects/synthetic/inline-packages/project-xyz.spdx.yml) +or [packages](https://github.com/oss-review-toolkit/ort/blob/main/plugins/package-managers/spdx/src/funTest/assets/projects/synthetic/libs/curl/package.spdx.yml). diff --git a/docusaurus/docs/tools/downloader.md b/docusaurus/docs/tools/downloader.md index f974a751a6ee..bbd92397dbb8 100644 --- a/docusaurus/docs/tools/downloader.md +++ b/docusaurus/docs/tools/downloader.md @@ -6,8 +6,9 @@ sidebar_position: 3 Taking an ORT result file with an *analyzer* result as the input (`-i`), the *downloader* retrieves the source code of all contained packages to the specified output directory (`-o`). The *downloader* takes care of things like normalizing -URLs and using the [appropriate VCS tool](./downloader/src/main/kotlin/vcs) to check out source code from version -control. +URLs and using the +[appropriate VCS tool](https://github.com/oss-review-toolkit/ort/blob/main/downloader/src/main/kotlin/vcs) to check out +source code from version control. Currently, the following Version Control Systems (VCS) are supported: diff --git a/docusaurus/docs/tools/evaluator.md b/docusaurus/docs/tools/evaluator.md index 0a2ac93d08d8..65021fd341cf 100644 --- a/docusaurus/docs/tools/evaluator.md +++ b/docusaurus/docs/tools/evaluator.md @@ -6,4 +6,4 @@ sidebar_position: 5 The *evaluator* is used to perform custom license policy checks on scan results. The rules to check against are implemented as Kotlin scripts with a dedicated DSL. See -[example.rules.kts](./examples/example.rules.kts) for an example rules script. +[example.rules.kts](../configuration/evaluator-rules.md#example) for an example rules script. diff --git a/docusaurus/docs/tools/reporter.md b/docusaurus/docs/tools/reporter.md index 9f97fe83fb15..7cff8101d9c0 100644 --- a/docusaurus/docs/tools/reporter.md +++ b/docusaurus/docs/tools/reporter.md @@ -7,7 +7,7 @@ sidebar_position: 6 The *reporter* generates a wide variety of documents in different formats from ORT result files. Currently, the following formats are supported (reporter names are case-insensitive): -* [AsciiDoc Template](docs/reporters/asciidoc-templates.md) (`-f AsciiDocTemplate`) +* [AsciiDoc Template](../configuration/reporter-templates.md#asciidoc-templates) (`-f AsciiDocTemplate`) * Content customizable with [Apache Freemarker](https://freemarker.apache.org/) templates and [AsciiDoc](https://asciidoc.org/) * PDF style customizable with Asciidoctor @@ -36,6 +36,7 @@ following formats are supported (reporter names are case-insensitive): * [TrustSource](https://www.trustsource.io/) JSON file (`-f TrustSource`) * Use this as an alternative to [ts-scan](https://github.com/TrustSource/ts-scan) for support of more build systems. * Web App (`-f WebApp`) - * Also see the [EvaluatedModelReporter](plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt) + * Also see the + [EvaluatedModelReporter](https://github.com/oss-review-toolkit/ort/blob/main/plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt) (`-f EvaluatedModel`) which is the JSON / YAML format used by the Web App report that is also suitable for custom post-processing. diff --git a/docusaurus/docs/tools/scanner.md b/docusaurus/docs/tools/scanner.md index b583c94f8057..0603fa2ba960 100644 --- a/docusaurus/docs/tools/scanner.md +++ b/docusaurus/docs/tools/scanner.md @@ -49,11 +49,13 @@ queried. Only if all of these steps fail, the scanner has to actually process th When storing a newly generated scan result the scanner invokes all the storages declared as writers. The storage operation is considered successful if all writer storages could successfully persist the scan result. -The configuration of storage backends is located in the [ORT configuration file](#ort-configuration-file). (For the -general structure of this file and the set of options available refer to the -[reference configuration](./model/src/main/resources/reference.yml).) The file has a section named *storages* that -lists all the storage backends and assigns them a name. Each storage backend is of a specific type and needs to be -configured with type-specific properties. The different types of storage backends supported by ORT are described below. +The configuration of storage backends is located in the +[ORT configuration file](../getting-started/usage.md#ort-configuration-file). (For the general structure of this file +and the set of options available refer to the +[reference configuration](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/resources/reference.yml).) +The file has a section named *storages* that lists all the storage backends and assigns them a name. Each storage +backend is of a specific type and needs to be configured with type-specific properties. The different types of storage +backends supported by ORT are described below. After the declaration of the storage backends, the configuration file has to specify which ones of them the scanner should use for looking up existing scan results or to store new results. This is done in two list properties @@ -136,7 +138,8 @@ store the data in a [jsonb](https://www.postgresql.org/docs/current/datatype-jso If you do not want to use SSL set the `sslmode` to `disable`, other possible values are explained in the [documentation](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client). For other supported -configuration options see [ScanStorageConfiguration.kt](./model/src/main/kotlin/config/ScanStorageConfiguration.kt). +configuration options see +[ScanStorageConfiguration.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/ScanStorageConfiguration.kt). ### ClearlyDefined Storage diff --git a/docusaurus/docusaurus.config.js b/docusaurus/docusaurus.config.js index 95c1d817af94..e30605ab2365 100644 --- a/docusaurus/docusaurus.config.js +++ b/docusaurus/docusaurus.config.js @@ -23,7 +23,7 @@ const config = { trailingSlash: false, onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'warn', + onBrokenMarkdownLinks: 'throw', // Even if you don't use internalization, you can use this field to set useful // metadata like html lang. For example, if your site is Chinese, you may want diff --git a/docusaurus/tutorial/intro.md b/docusaurus/tutorial/intro.md index 337a91b35da0..1d3526135aa0 100644 --- a/docusaurus/tutorial/intro.md +++ b/docusaurus/tutorial/intro.md @@ -33,7 +33,7 @@ tools need to be installed. In the context of this tutorial the following tools * [NPM](https://www.npmjs.com) 6.4.* or higher. * [Yarn](https://yarnpkg.com) 1.9.* or higher. -For the full list of supported package managers and Version Control Systems see the [README](../README.md). +For the full list of supported package managers and Version Control Systems see the [README](../docs/tools/analyzer). ## 2. Download & Install ORT @@ -122,7 +122,7 @@ Note that the `analyzer-result.yml` is supposed to capture all known information "filtered" in later steps. For example, scopes which are not relevant for the distribution will still be listed, but can be configured to get excluded so that they e.g. do not get downloaded and scanned by the *scanner* step. To specify which scopes should be excluded, add an `.ort.yml` configuration file to the input directory of the -*analyzer*. For more details see [Configuration File](config-file-ort-yml.md). +*analyzer*. For more details see [Configuration File](../docs/configuration/ort-yml). For this guide, `[mime-types-dir]/.ort.yml` can be created with following content: @@ -257,7 +257,7 @@ needs to be downloaded. The *downloader* tool could be used for this, but it is so the scanner will automatically download the source code if the required VCS metadata could be obtained. Note that if the *downloader* is unable to download the source code due to say a missing source code location in the -package metadata then you can use [curations](config-file-curations-yml.md) to fix up the package's metadata. +package metadata then you can use [curations](../docs/configuration/package-curations) to fix up the package's metadata. ORT is designed to integrate lots of different scanners and is not limited to license scanners, technically any tool that explores the source code of a software package could be integrated. The actual scanner does not have to run on the @@ -276,7 +276,7 @@ cli/build/install/ort/bin/ort scan --help The `mime-types` package has only one dependency in the `dependencies` scope, but a lot of dependencies in the `devDependencies` scope. Scanning all of the `devDependencies` would take a lot of time, so we will only run the scanner on the `dependencies` scope in this tutorial. If you also want to scan the `devDependencies` it is strongly -advised to configure a [scan storage](../README.md#storage-backends) for the scan results to speed up repeated scans. +advised to configure a [scan storage](../docs/tools/scanner#storage-backends) for the scan results to speed up repeated scans. As during the *analyzer* step an `.ort.yml` configuration file was provided to exclude `devDependencies`, the `--skip-excluded` option can be used to avoid the download and scanning of that scope. @@ -305,10 +305,10 @@ on a bigger project you will see that `ScanCode` often finds more licenses than ## 6. Running the evaluator -The evaluator can apply a set of rules against the scan result created above. -ORT provides examples for the policy rules file ([example.rules.kts](../examples/example.rules.kts)), user-defined -categorization of licenses ([license-classifications.yml](../examples/license-classifications.yml)) and user-defined -package curations ([curations.yml](../examples/curations.yml)) that can be used for testing the *evaluator*. +The evaluator can apply a set of rules against the scan result created above. ORT provides examples for the policy rules +file ([example.rules.kts](../docs/configuration/evaluator-rules#example)), user-defined categorization of licenses +([license-classifications.yml](../docs/configuration/license-classifications)) and user-defined package curations +([curations.yml](../docs/configuration/package-curations)) that can be used for testing the *evaluator*. To run the example rules use: @@ -321,9 +321,9 @@ cli/build/install/ort/bin/ort evaluate -o [evaluator-output-dir]/mime-types ``` -See the [curations.yml documentation](config-file-curations-yml.md) to learn more about using curations to correct +See the [curations.yml documentation](../docs/configuration/package-curations) to learn more about using curations to correct invalid or missing package metadata and the -[license-classifications.yml documentation](config-file-license-classifications-yml.md) on how you can classify licenses +[license-classifications.yml documentation](../docs/configuration/license-classifications) on how you can classify licenses to simplify writing the policy rules. It is possible to write your own evaluator rules as a Kotlin script and pass it to the *evaluator* using `--rules-file`. @@ -348,8 +348,8 @@ Created 'PlainTextTemplate' report: [reporter-output-dir]/NOTICE_DEFAULT If you do not want to run the *evaluator* you can pass the *scanner* result e.g. `[scanner-output-dir]/scan-result.yml` to the `reporter` instead. To learn how you can customize generated notices see -[plain-text-templates.md](reporters/plain-text-templates.md). To learn how to customize the how-to-fix texts for scanner -and analyzer issues see [how-to-fix-text-provider-kts.md](scripts/how-to-fix-text-provider-kts.md). +[Reporter Templates](../docs/configuration/reporter-templates#plain-text-templates). To learn how to customize the how-to-fix texts for scanner +and analyzer issues see [how-to-fix-text-provider-kts.md](../docs/configuration/how-to-fix-text-provider). ## 8. Curating Package Metadata or License Findings @@ -359,11 +359,11 @@ repositories are not correctly tagged. ORT provides a variety of mechanisms to fix a variety of issues, for details see: -* [The .ort.yml file](config-file-ort-yml.md) - project-specific license finding curations, exclusions and resolutions +* [The .ort.yml file](../docs/configuration/ort-yml) - project-specific license finding curations, exclusions and resolutions to address issues found within a project's code repository. -* [The package configuration file](config-file-package-configuration-yml.md) - package (dependency) and provenance +* [The package configuration file](../docs/configuration/package-configurations) - package (dependency) and provenance specific license finding curations and exclusions to address issues found within a scan result for a package. -* [The curations.yml file](config-file-curations-yml.md) - curations correct invalid or missing package metadata and set +* [The curations.yml file](../docs/configuration/package-curations) - curations correct invalid or missing package metadata and set the concluded license for packages. -* [The resolutions.yml file](config-file-resolutions-yml.md) - resolutions allow *resolving* any issues or policy rule +* [The resolutions.yml file](../docs/configuration/resolutions) - resolutions allow *resolving* any issues or policy rule violations by providing a reason why they are acceptable and can be ignored.