Skip to content

Commit 7f89644

Browse files
sreyasreya
committed
Simplify to use Redocly HTML output converted to markdown
Remove custom OpenAPI parser and use a cleaner approach: - Generate HTML documentation with Redocly CLI - Convert HTML to markdown using turndown library - Maintain compatibility with existing postprocessor This approach: - Uses Redocly's comprehensive HTML output (3.3MB) - Converts to 959KB of markdown documentation - Generates a single comprehensive API documentation file - Leverages Redocly's excellent documentation generation - Keeps the solution simple and maintainable Co-authored-by: sreya <4856196+sreya@users.noreply.github.com>
1 parent 23c8c24 commit 7f89644

File tree

8 files changed

+78
-327
lines changed

8 files changed

+78
-327
lines changed

‎scripts/apidocgen/generate.sh

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,22 @@ pushd "${APIDOCGEN_DIR}"
3131
# Make sure that redocly is installed correctly.
3232
pnpm exec -- redocly --version
3333
# Generate basic markdown structure (redocly doesn't have direct markdown output like widdershins)
34-
# Generate comprehensive markdown documentation from OpenAPI spec
35-
# Validate the OpenAPI spec with redocly first
34+
# Generate markdown documentation using Redocly
35+
# First validate the OpenAPI spec
3636
log "Validating OpenAPI spec with Redocly..."
3737
pnpm exec -- redocly lint "../../coderd/apidoc/swagger.json" > /dev/null 2>&1 || true
3838

39-
# Generate markdown using our custom converter that produces output similar to Widdershins
40-
log "Generating comprehensive markdown documentation..."
41-
node openapi-to-markdown.js "../../coderd/apidoc/swagger.json" "${API_MD_TMP_FILE}"
39+
# Generate HTML documentation with Redocly
40+
log "Generating HTML documentation with Redocly..."
41+
HTML_TMP_FILE=$(mktemp /tmp/coder-apidoc-html.XXXXXX)
42+
pnpm exec -- redocly build-docs "../../coderd/apidoc/swagger.json" --output "${HTML_TMP_FILE}"
43+
44+
# Convert HTML to markdown
45+
log "Converting HTML to markdown..."
46+
node html-to-markdown.js "${HTML_TMP_FILE}" "${API_MD_TMP_FILE}"
47+
48+
# Clean up HTML file
49+
rm -f "${HTML_TMP_FILE}"
4250
# Perform the postprocessing
4351
go run postprocess/main.go -in-md-file-single "${API_MD_TMP_FILE}"
4452
popd

‎scripts/apidocgen/generate_original.sh

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎scripts/apidocgen/generate_true_original.sh

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎scripts/apidocgen/html-to-markdown.js

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#!/usr/bin/env node
2+
3+
const fs = require('fs');
4+
const TurndownService = require('turndown');
5+
6+
if (process.argv.length < 4) {
7+
console.error('Usage: node html-to-markdown.js <input.html> <output.md>');
8+
process.exit(1);
9+
}
10+
11+
const inputFile = process.argv[2];
12+
const outputFile = process.argv[3];
13+
14+
try {
15+
// Read HTML file
16+
const html = fs.readFileSync(inputFile, 'utf8');
17+
18+
// Configure turndown
19+
const turndownService = new TurndownService({
20+
headingStyle: 'atx',
21+
codeBlockStyle: 'fenced'
22+
});
23+
24+
// Convert HTML to markdown
25+
let markdown = turndownService.turndown(html);
26+
27+
// Add section separators for the postprocessor
28+
// Split by main headings and add section markers
29+
const sections = markdown.split(/^# /m);
30+
let processedMarkdown = '';
31+
32+
for (let i = 1; i < sections.length; i++) {
33+
processedMarkdown += '<!-- APIDOCGEN: BEGIN SECTION -->\n';
34+
processedMarkdown += '# ' + sections[i];
35+
if (i < sections.length - 1) {
36+
processedMarkdown += '\n\n';
37+
}
38+
}
39+
40+
// Write markdown file
41+
fs.writeFileSync(outputFile, processedMarkdown);
42+
43+
console.log(`Successfully converted ${inputFile} to ${outputFile}`);
44+
45+
} catch (error) {
46+
console.error('Error:', error.message);
47+
process.exit(1);
48+
}

‎scripts/apidocgen/openapi-to-markdown.js

Lines changed: 0 additions & 211 deletions
This file was deleted.

‎scripts/apidocgen/package.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"dependencies": {
3-
"@redocly/cli": "^1.25.11"
3+
"@redocly/cli": "^1.25.11",
4+
"turndown": "^7.2.0"
45
},
56
"resolutions": {
67
"semver": "7.5.3",

0 commit comments

Comments
 (0)