Skip to content

Commit ecdf261

Browse files
authored
Remove relative links to other docs (#60)
Crates.io cannot handle relative links from a workspace README, causing a difference between the GitHub landing page and crates.io
1 parent 72dc0c1 commit ecdf261

1 file changed

Lines changed: 14 additions & 13 deletions

File tree

README.md

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,12 @@ because at best, only leaf requirements (those without children) must be traced
3737
8. Repeat from step 2 until the project is complete
3838

3939
For a quick overview of those steps, see the [getting-started section](#getting-started) below.
40-
More details about using and configuring *mantra* may be found in the [/docs/usage](docs/usage/README.md) folder.
40+
More details about using and configuring *mantra* may be found in the `/docs/usage` folder.
4141
The goals, requirements, and decisions behind *mantra* are documented under `/docs/wiki`, which is also published on *mantra*'s [GitHub wiki](https://github.com/mhatzl/mantra/wiki).
4242

4343
**Note:** Currently, focus is on support for Rust code, but built-in support for other languages is planned.
4444
If your language is not supported directly, you may create your own tooling that extracts relevant information
45-
and converts it into a format *mantra* understands following *mantra*'s [JSON schemas](schema-gen/README.md).
45+
and converts it into a format *mantra* understands following *mantra*'s JSON schemas available at `schema-gen/generated`.
4646

4747
## Installation
4848

@@ -63,7 +63,7 @@ cargo install --locked mantra
6363
## Usage
6464

6565
This section provides a high-level overview to get you started using *mantra*.
66-
For more details, take a look at the [/docs/usage](docs/usage/README.md) folder.
66+
For more details, take a look at the `/docs/usage` folder.
6767

6868
In order to use *mantra* for Rust projects, you typically want the following prerequisites installed:
6969

@@ -113,17 +113,17 @@ products: [{
113113
```
114114

115115
Based on this configuration, files defining requirements are expected to be located under the `reqs/` folder
116-
following the [RequirementSchema](schema-gen/generated/collect/RequirementSchema.json).
116+
following the `RequirementSchema`.
117117
Annotations such as requirement traces are extracted from Rust code files located in the repository.
118118
Test and code coverage results are expected under `target/nextest/default`, with test results following the [JUnit XML](https://llg.cubic.org/docs/junit/) format and code coverage being represented in the [Cobertura Loose XML](https://github.com/cobertura/cobertura/blob/master/cobertura/src/site/htdocs/xml/coverage-loose.dtd) format.
119119
Files containing manual reviews are expected to be located under the `reviews/` folder
120-
following the [ReviewSchema](schema-gen/generated/collect/ReviewSchema.json).
120+
following the `ReviewSchema`.
121121

122-
More details related to *mantra*'s configuration file can be found under [/docs/usage/configuration](docs/usage/configuration.md).
122+
More details related to *mantra*'s configuration file can be found under `/docs/usage/configuration.md`.
123123

124124
### Defining Requirements
125125

126-
Currently, only the [RequirementSchema](schema-gen/generated/collect/RequirementSchema.json) is supported as input for requirement definitions.
126+
Currently, only the `RequirementSchema` is supported as input for requirement definitions.
127127

128128
The following configuration defines three requirements `gs-req-1`, `gs-req-2`, and `gs-req-1.sub-1`:
129129

@@ -170,12 +170,12 @@ even if `gs-req-1.sub-1` is `unverified` or `skipped`.
170170

171171
### Tracing Requirements in Code
172172

173-
Currently, *mantra* is only able to detect traces in Rust code that match the macros defined in the [mantra-macros](langs/rust/mantra-macros) crate.
173+
Currently, *mantra* is only able to detect traces in Rust code that match the macros defined in the [mantra-macros](https://crates.io/crates/mantra-macros) crate.
174174
Note that it is not required to use this crate, because trace detection is only based on macro names.
175175
For other languages and file formats, external tools may convert extracted data into the
176-
[AnnotationSchema](schema-gen/generated/collect/AnnotationSchema.json).
176+
`AnnotationSchema`.
177177

178-
If you want to use the macros from [mantra-macros](langs/rust/mantra-macros/README.md),
178+
If you want to use the macros from [mantra-macros](https://crates.io/crates/mantra-macros),
179179
add it to your Cargo.toml via
180180

181181
```sh
@@ -217,8 +217,9 @@ The benefit is that combining traces with line coverage allows users to choose b
217217
For example, if a `verifies` trace is set on a test and there is a code part with a `satisfies` trace to the same requirement, *mantra* checks if the test actually passed this code part.
218218

219219
For Rust projects, a convenient way to get test and coverage results that are readable by *mantra*
220-
is to use [cargo-nextest](https://nexte.st/) with the JUnit feature and [grcov](https://github.com/mozilla/grcov/) with the Cobertura output format. See the `testcov` task in the [justfile](justfile) of the repository to see how this is set up for *mantra*.
221-
This convenience layer is internally converted to the [TestRunSchema](schema-gen/generated/collect/TestRunSchema.json), which external tools may target directly.
220+
is to use [cargo-nextest](https://nexte.st/) with the JUnit feature and [grcov](https://github.com/mozilla/grcov/) with the Cobertura output format.
221+
See the `testcov` task in the `justfile` of the repository to see how this is set up for *mantra*.
222+
This convenience layer is internally converted to the `TestRunSchema`, which external tools may target directly.
222223

223224
**Note:** Code coverage for Rust projects collected via `-Cinstrument-coverage` is only collected per binary.
224225
Consequently, it is not possible to get code coverage results per test case, which worsens the safety guarantees
@@ -232,7 +233,7 @@ to explicitly state that this requirement must be verified manually in a review.
232233
Besides verifying requirements, reviews may also be used to overwrite test results,
233234
which is for example useful in case of flaky tests.
234235

235-
Currently, can only be added following the [ReviewSchema](schema-gen/generated/collect/ReviewSchema.json).
236+
Currently, reviews can only be added following the `ReviewSchema`.
236237
External tools may be used to extract data from other formats and convert to the schema.
237238

238239
The review below verifies the manual requirement `gs-req-2`:

0 commit comments

Comments
 (0)