Skip to content

Commit

Permalink
✅ Test markdown links in all docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ebullient
ebullient committed Dec 27, 2023
1 parent 3defe27 commit ade393a
Show file tree
Hide file tree
Showing 5 changed files with 53 additions and 24 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ See [Other ways to run the CLI](docs/alternateRun.md) for more options to downlo
git clone --depth 1 https://github.com/Pf2eToolsOrg/Pf2eTools.git
```
2. Invoke the CLI. In this first example, let's generate indexes and use only SRD content (using the alias set up when [installing the cli](#install-the-ttrpg-convert-cli)):
2. Invoke the CLI. In this first example, let's generate indexes and use only SRD content (using the alias set up when [installing the cli](#install-the-ttrpg-convert-cli):
```shell
ttrpg-convert \
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/dev/ebullient/convert/Pf2eDataConvertTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ void testLiveData_Pf2eAllSources(QuarkusMainLauncher launcher) {

TestUtils.assertDirectoryContents(allIndex, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> TestUtils.checkMarkdownLinks(allIndex.toString(), p, l, errors));
content.forEach(l -> TestUtils.checkMarkdownLink(allIndex.toString(), p, l, errors));
return errors;
});
}
Expand Down
48 changes: 41 additions & 7 deletions src/test/java/dev/ebullient/convert/TestUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,7 @@ public class TestUtils {
public final static Path PATH_5E_UA = PROJECT_PATH.resolve("sources/5e-unearthed-arcana");
public final static Path TOOLS_PATH_PF2E = PROJECT_PATH.resolve("sources/Pf2eTools/data");

public final static Path README = PROJECT_PATH.resolve("README.md").normalize().toAbsolutePath();
static String USAGE = PROJECT_PATH.resolve("docs").normalize().toAbsolutePath().toString();
static String GENERATED_DOCS = PROJECT_PATH.resolve("docs/templates").normalize().toAbsolutePath().toString();

// Obnoxious regular expression because markdown links are complicated:
// Matches: [link text](vaultPath "title")
Expand Down Expand Up @@ -85,12 +84,13 @@ static void assertContents(Path path1, Path path2, boolean areEqual) throws IOEx
}
}

public static void checkMarkdownLinks(String baseDir, Path p, String line, List<String> errors) {
public static void checkMarkdownLink(String baseDir, Path p, String line, List<String> errors) {
Path absPath = p.normalize().toAbsolutePath();
if (!absPath.toString().endsWith(".md") || absPath.equals(README) || absPath.toString().startsWith(USAGE)) {
if (!absPath.toString().endsWith(".md")) {
// GH anchor links
return;
}
final boolean githubStyle = !absPath.toString().startsWith(GENERATED_DOCS);
List<String> e = new ArrayList<>();
// replace (Level x) or (1st level) or (Firearms) with :whatever: to simplify matching
Matcher links = markdownLinkPattern.matcher(line);
Expand Down Expand Up @@ -140,7 +140,7 @@ public static void checkMarkdownLinks(String baseDir, Path p, String line, List<
} else {
String heading = simplifyAnchor(anchor).replaceAll("%20", " ");
String ghHeading = heading.replace("-", " ");
List<String> headings = findHeadingsIn(resource);
List<String> headings = findHeadingsIn(resource, githubStyle);
// obsidian or github style anchors
if (!headings.contains(heading) && !headings.contains(ghHeading)) {
e.add(String.format("Unresolvable anchor (%s) in %s: %s", heading, p, m.group(0)));
Expand All @@ -151,7 +151,7 @@ public static void checkMarkdownLinks(String baseDir, Path p, String line, List<
errors.addAll(e);
}

public static List<String> findHeadingsIn(Path p) {
public static List<String> findHeadingsIn(Path p, boolean githubStyle) {
if (!p.toString().endsWith(".md")) {
return List.of();
}
Expand All @@ -163,7 +163,12 @@ public static List<String> findHeadingsIn(Path p) {
if (l.contains(".")) {
System.out.println("🔮 Found dot in heading in " + p + ": " + l);
}
headings.add(simplifyAnchor(l));
l = simplifyAnchor(l);
if (githubStyle) {
l = l.replace("`", "")
.replace("-", " ");
}
headings.add(l);
}
});
} catch (UncheckedIOException | IOException e) {
Expand Down Expand Up @@ -265,6 +270,34 @@ public static void assertDirectoryContents(Path directory, Tui tui, BiFunction<P
assertThat(errors).isEmpty();
}

public static void assertMarkdownLinks(Path filePath, Tui tui) {
List<String> errors = new ArrayList<>();
testMarkdownLinks(filePath, tui, errors);
assertThat(errors).isEmpty();
}

private static void testMarkdownLinks(Path filePath, Tui tui, List<String> errors) {
if (filePath.toFile().isDirectory()) {
try (Stream<Path> walk = Files.list(filePath)) {
walk.forEach(p -> {
testMarkdownLinks(p, tui, errors);
});
} catch (IOException e) {
e.printStackTrace();
errors.add(String.format("Unable to parse files in directory %s: %s", filePath, e));
}
} else {
try {
Files.readAllLines(filePath).forEach(l -> {
TestUtils.checkMarkdownLink(filePath.toString(), filePath, l, errors);
});
} catch (IOException e) {
e.printStackTrace();
errors.add(String.format("Unable to read lines from %s: %s", filePath, e));
}
}
}

static List<String> checkDirectoryContents(Path directory, Tui tui,
BiFunction<Path, List<String>, List<String>> checker) {
List<String> errors = new ArrayList<>();
Expand All @@ -287,6 +320,7 @@ static List<String> checkDirectoryContents(Path directory, Tui tui,
}
if (!p.toString().endsWith(".md")) {
if (!p.toString().endsWith(".png")
&& !p.toString().endsWith(".txt")
&& !p.toString().endsWith(".jpg")
&& !p.toString().endsWith(".css")
&& !p.toString().endsWith(".svg")
Expand Down
10 changes: 5 additions & 5 deletions src/test/java/dev/ebullient/convert/Tools5eDataConvertTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ void testLiveData_5eAllSources(QuarkusMainLauncher launcher) {
TestUtils.assertDirectoryContents(allIndex, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> {
TestUtils.checkMarkdownLinks(allIndex.toString(), p, l, errors);
TestUtils.checkMarkdownLink(allIndex.toString(), p, l, errors);
TestUtils.commonTests(p, l, errors);
});
return errors;
Expand All @@ -105,7 +105,7 @@ void testLiveData_5eOneSource(QuarkusMainLauncher launcher) {
TestUtils.assertDirectoryContents(target, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> {
TestUtils.checkMarkdownLinks(target.toString(), p, l, errors);
TestUtils.checkMarkdownLink(target.toString(), p, l, errors);
TestUtils.commonTests(p, l, errors);
if (l.matches(".*-ua[^.]\\.md.*$")) {
errors.add(String.format("Found UA resources in %s: %s", p.toString(), l));
Expand Down Expand Up @@ -167,7 +167,7 @@ void testLiveData_5eHomebrew(QuarkusMainLauncher launcher) {
TestUtils.assertDirectoryContents(target, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> {
TestUtils.checkMarkdownLinks(target.toString(), p, l, errors);
TestUtils.checkMarkdownLink(target.toString(), p, l, errors);
TestUtils.commonTests(p, l, errors);
});
return errors;
Expand Down Expand Up @@ -210,7 +210,7 @@ void testLiveData_5eUA(QuarkusMainLauncher launcher) {
TestUtils.assertDirectoryContents(target, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> {
TestUtils.checkMarkdownLinks(target.toString(), p, l, errors);
TestUtils.checkMarkdownLink(target.toString(), p, l, errors);
TestUtils.commonTests(p, l, errors);
});
return errors;
Expand Down Expand Up @@ -250,7 +250,7 @@ void testCommand_5eBookAdventureInJson(QuarkusMainLauncher launcher) {
TestUtils.assertDirectoryContents(target, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> {
TestUtils.checkMarkdownLinks(target.toString(), p, l, errors);
TestUtils.checkMarkdownLink(target.toString(), p, l, errors);
TestUtils.commonTests(p, l, errors);
if (l.contains("/ru les/")) {
errors.add("Found '/ru les/' " + p); // not escaped
Expand Down
15 changes: 5 additions & 10 deletions src/test/java/dev/ebullient/convert/docs/TemplateDocTest.java
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
package dev.ebullient.convert.docs;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
Expand Down Expand Up @@ -34,11 +30,10 @@ public void buildVerifyDocs() throws Exception {
@Test
@EnabledIfSystemProperty(named = "maven.home", matches = ".*")
public void verifyDocs() throws Exception {
Path docs = TestUtils.PROJECT_PATH.resolve("docs");
TestUtils.assertDirectoryContents(docs, tui, (p, content) -> {
List<String> errors = new ArrayList<>();
content.forEach(l -> TestUtils.checkMarkdownLinks(docs.toString(), p, l, errors));
return errors;
});
TestUtils.assertMarkdownLinks(TestUtils.PROJECT_PATH.resolve("docs"), tui);
TestUtils.assertMarkdownLinks(TestUtils.PROJECT_PATH.resolve("examples"), tui);
TestUtils.assertMarkdownLinks(TestUtils.PROJECT_PATH.resolve("README.md"), tui);
TestUtils.assertMarkdownLinks(TestUtils.PROJECT_PATH.resolve("README-WINDOWS.md"), tui);
TestUtils.assertMarkdownLinks(TestUtils.PROJECT_PATH.resolve("CHANGELOG.md"), tui);
}
}

0 comments on commit ade393a

Please sign in to comment.