search

intel / rohd

The Rapid Open Hardware Development (ROHD) framework is a framework for describing and verifying hardware in the Dart programming language.
https://intel.github.io/rohd-website
BSD 3-Clause "New" or "Revised" License
374 stars 67 forks source link

Add check for Markdown links in CI #276

Closed chykon closed 1 year ago

chykon commented 1 year ago

Description & Motivation

Motivation

Since the ROHD project uses Markdown for writing documentation and tutorials, it would be nice to make things easier to work with. One of them is link checking. As evidence of the urgency of the problem, you can refer here:

  1. https://github.com/intel/rohd/pull/221#discussion_r1097825483
  2. https://github.com/intel/rohd/pull/266#discussion_r1104862385

The proposed changes will completely solve the problem from the first point and mitigate the problem from the second point.

Description

The changes themselves are:

The risks of adding a new action are minimal as it is executed in a job without permissions (permissions: {}).

The configuration file comes with the address already added to the ignore list because there were false positives. An attempt to go to the address from a personal device without a proxy also failed, but the site is accessible when using a proxy. Probably DDoS protection applied.

Problems

Limited anchor link checking: available in beta and only for headers located in the document itself (there is an open issue: https://github.com/tcort/markdown-link-check/issues/212).

Some alternative solutions have been explored, but all have a problem with handling anchor links pointing to other documents.

Related Issue(s)

No.

Testing

Several launches were made on our own branch:

  1. (https://github.com/chykon/rohd/actions/runs/4196972120/jobs/7278680046) First run with a false positive. FAILURE.
  2. (https://github.com/chykon/rohd/actions/runs/4197452723/jobs/7279783587) Second run with added ignore rule. SUCCESS.
  3. (https://github.com/chykon/rohd/actions/runs/4197728761/jobs/7280432455) Third run with test files test_a.md and test_b.md demonstrating the ability to test anchor links. FAILURE.

Backwards-compatibility

Is this a breaking change that will not be backwards-compatible? If yes, how so?

No.

Documentation

Does the change require any updates to documentation? If so, where? Are they included?

No.

mkorbel1 commented 1 year ago

Filed issues to implement this same thing in ROHD Cosim and ROHD-VF: https://github.com/intel/rohd-cosim/issues/24 https://github.com/intel/rohd-vf/issues/37