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:
Родитель
950ff224ba
Коммит
ebc8ce6fa0
|
@ -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')
|
||||
|
|
|
@ -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!");
|
||||
}
|
||||
}
|
Загрузка…
Ссылка в новой задаче