Validate docs have a `title:` and fix for astro migration (#2561)

Astro requires every doc to have a title. Adding a simple script to
validate that so we don't have to patch things when migrating.
This commit is contained in:
Timothee Guerin 2023-10-11 10:09:05 -07:00 коммит произвёл GitHub
Родитель 950ff224ba
Коммит ebc8ce6fa0
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
11 изменённых файлов: 94 добавлений и 9 удалений

Просмотреть файл

@ -1,4 +1,6 @@
# Diagnostics
---
title: Diagnostics
---
TypeSpec compiler report errors and warnings in the spec using the diagnostic API.

Просмотреть файл

@ -1,4 +1,6 @@
# Getting Started with TypeSpec For Http
---
title: Getting Started with TypeSpec For Http
---
Let's create a REST API definition with TypeSpec. TypeSpec has an official HTTP API "binding" called `@typespec/http`. It's a set of TypeSpec declarations and decorators that describe HTTP APIs and can be used by code generators to generate OpenAPI descriptions, implementation code, and the like.
Built on top of the http library there is the rest library `@typespec/rest` which provide some REST concept like resources.

Просмотреть файл

@ -1,4 +1,6 @@
# TypeSpec Visual Studio Extension
---
title: TypeSpec Visual Studio Extension
---
## Installation

Просмотреть файл

@ -1,4 +1,6 @@
# TypeSpec VSCode extension
---
title: TypeSpec VSCode extension
---
## Installation

Просмотреть файл

@ -1,4 +1,6 @@
# Reproducibility
---
title: Reproducibility
---
A key point to service definition is the ability to reliably reproduce the exact same output over time. In cases like:

Просмотреть файл

@ -1,4 +1,6 @@
# Cadl to TypeSpec rename completed in March 2023 release
---
title: Cadl to TypeSpec rename completed in March 2023 release
---
As you may recall from our previous email to partners, we are renaming the product as it becomes more mature, stable and one step closer to release.

Просмотреть файл

@ -1,4 +1,6 @@
# Discriminated types
---
title: Discriminated types
---
TypeSpec can express unions and inheritance. However, when sending types over the wire many languages need a way to discriminate between the various union variants or models in an inheritance hierarchy.

Просмотреть файл

@ -1,4 +1,6 @@
# Content types
---
title: Content types
---
## Default behavior

Просмотреть файл

@ -1,4 +1,6 @@
# Encoding of types
---
title: Encoding of types
---
This document describe how the http library interpret TypeSpec built-in types and how to configure

Просмотреть файл

@ -27,6 +27,10 @@ steps:
- script: node eng/scripts/check-for-changed-files.js
displayName: Check Git Status For Changed Files
- script: node eng/scripts/check-docs.js
displayName: Check docs
condition: ne(variables['Agent.OS'], 'Windows_NT')
- script: node common/scripts/install-run-rush.js cspell
displayName: Spell check
condition: ne(variables['Agent.OS'], 'Windows_NT')

63
eng/scripts/check-docs.js Normal file
Просмотреть файл

@ -0,0 +1,63 @@
// @ts-check
// cspell:ignore astro
// This script check the docs are compatible for astro to simplify migration
// It check each docs has
// - a `title:` frontmatter
import { readFile, readdir } from "fs/promises";
import { resolve } from "path";
import { repoRoot } from "./helpers.js";
const docsFolder = resolve(repoRoot, "docs");
async function findMarkdownFiles(folder) {
const items = await readdir(folder, { withFileTypes: true });
return (
await Promise.all(
items.map(async (item) => {
if (item.isDirectory()) {
const files = await findMarkdownFiles(resolve(folder, item.name));
return files.map((x) => resolve(folder, x));
}
if (item.name.endsWith(".md")) {
return [resolve(folder, item.name)];
} else {
return [];
}
})
)
).flat();
}
await main();
async function main() {
const docs = await findMarkdownFiles(docsFolder);
const failure = [];
const regex = /^---.*title:.*---$/ms;
for (const doc of docs) {
const buffer = await readFile(doc, { encoding: "utf-8" });
const content = buffer.toString();
if (!regex.test(content)) {
failure.push(doc);
}
}
if (failure.length > 0) {
console.log("Files with missing title: frontmatter", failure);
console.log(
[
"Make sure to add front matter in the file with title, e.g.:",
"---",
"title: xyz",
"---",
].join("\n")
);
process.exit(1);
} else {
console.log("Docs look good!");
}
}