mapcomplete/scripts/generateDocs.ts

import Combine from "../UI/Base/Combine"
import BaseUIElement from "../UI/BaseUIElement"
import Translations from "../UI/i18n/Translations"
import { existsSync, mkdirSync, writeFileSync } from "fs"
import { AllKnownLayouts } from "../Customizations/AllKnownLayouts"
import TableOfContents from "../UI/Base/TableOfContents"
import SimpleMetaTaggers from "../Logic/SimpleMetaTagger"
import ValidatedTextField from "../UI/Input/ValidatedTextField"
import SpecialVisualizations from "../UI/SpecialVisualizations"
import { ExtraFunctions } from "../Logic/ExtraFunctions"
import Title from "../UI/Base/Title"
import Minimap from "../UI/Base/Minimap"
import QueryParameterDocumentation from "../UI/QueryParameterDocumentation"
import ScriptUtils from "./ScriptUtils"
import List from "../UI/Base/List"
import SharedTagRenderings from "../Customizations/SharedTagRenderings"

function WriteFile(
    filename,
    html: BaseUIElement,
    autogenSource: string[],
    options?: {
        noTableOfContents: boolean
    }
): void {
    for (const source of autogenSource) {
        if (source.indexOf("*") > 0) {
            continue
        }
        if (!existsSync(source)) {
            throw (
                "While creating a documentation file and checking that the generation sources are properly linked: source file " +
                source +
                " was not found. Typo?"
            )
        }
    }

    if (html instanceof Combine && !options?.noTableOfContents) {
        const toc = new TableOfContents(html)
        const els = html.getElements()
        html = new Combine([els.shift(), toc, ...els]).SetClass("flex flex-col")
    }

    let md = new Combine([
        Translations.W(html),
        "\n\nThis document is autogenerated from " +
            autogenSource
                .map(
                    (file) =>
                        `[${file}](https://github.com/pietervdvn/MapComplete/blob/develop/${file})`
                )
                .join(", "),
    ]).AsMarkdown()

    md.replace(/\n\n\n+/g, "\n\n")

    writeFileSync(filename, md)
}

console.log("Starting documentation generation...")
AllKnownLayouts.GenOverviewsForSingleLayer((layer, element, inlineSource) => {
    console.log("Exporting ", layer.id)
    if (!existsSync("./Docs/Layers")) {
        mkdirSync("./Docs/Layers")
    }
    let source: string = `assets/layers/${layer.id}/${layer.id}.json`
    if (inlineSource !== undefined) {
        source = `assets/themes/${inlineSource}/${inlineSource}.json`
    }
    WriteFile("./Docs/Layers/" + layer.id + ".md", element, [source], { noTableOfContents: true })
})
WriteFile("./Docs/SpecialRenderings.md", SpecialVisualizations.HelpMessage(), [
    "UI/SpecialVisualizations.ts",
])
WriteFile(
    "./Docs/CalculatedTags.md",
    new Combine([
        new Title("Metatags", 1),
        SimpleMetaTaggers.HelpText(),
        ExtraFunctions.HelpText(),
    ]).SetClass("flex-col"),
    ["Logic/SimpleMetaTagger.ts", "Logic/ExtraFunctions.ts"]
)
WriteFile("./Docs/SpecialInputElements.md", ValidatedTextField.HelpText(), [
    "UI/Input/ValidatedTextField.ts",
])
WriteFile("./Docs/BuiltinLayers.md", AllKnownLayouts.GenLayerOverviewText(), [
    "Customizations/AllKnownLayouts.ts",
])
WriteFile("./Docs/BuiltinQuestions.md", SharedTagRenderings.HelpText(), [
    "Customizations/SharedTagRenderings.ts",
    "assets/tagRenderings/questions.json",
])

{
    // Generate the builtinIndex which shows interlayer dependencies
    var layers = ScriptUtils.getLayerFiles().map((f) => f.parsed)
    var builtinsPerLayer = new Map<string, string[]>()
    var layersUsingBuiltin = new Map<string /* Builtin */, string[]>()
    for (const layer of layers) {
        if (layer.tagRenderings === undefined) {
            continue
        }
        const usedBuiltins: string[] = []
        for (const tagRendering of layer.tagRenderings) {
            if (typeof tagRendering === "string") {
                usedBuiltins.push(tagRendering)
                continue
            }
            if (tagRendering["builtin"] !== undefined) {
                const builtins = tagRendering["builtin"]
                if (typeof builtins === "string") {
                    usedBuiltins.push(builtins)
                } else {
                    usedBuiltins.push(...builtins)
                }
            }
        }
        for (const usedBuiltin of usedBuiltins) {
            var using = layersUsingBuiltin.get(usedBuiltin)
            if (using === undefined) {
                layersUsingBuiltin.set(usedBuiltin, [layer.id])
            } else {
                using.push(layer.id)
            }
        }

        builtinsPerLayer.set(layer.id, usedBuiltins)
    }

    const docs = new Combine([
        new Title("Index of builtin TagRendering", 1),
        new Title("Existing builtin tagrenderings", 2),
        ...Array.from(layersUsingBuiltin.entries()).map(([builtin, usedByLayers]) =>
            new Combine([new Title(builtin), new List(usedByLayers)]).SetClass("flex flex-col")
        ),
    ]).SetClass("flex flex-col")
    WriteFile("./Docs/BuiltinIndex.md", docs, ["assets/layers/*.json"])
}

Minimap.createMiniMap = (_) => {
    console.log("Not creating a minimap, it is disabled")
    return undefined
}

WriteFile("./Docs/URL_Parameters.md", QueryParameterDocumentation.GenerateQueryParameterDocs(), [
    "Logic/Web/QueryParameters.ts",
    "UI/QueryParameterDocumentation.ts",
])

console.log("Generated docs")