mapcomplete/scripts/generateDocs.ts

import Combine from "../UI/Base/Combine";
import BaseUIElement from "../UI/BaseUIElement";
import Translations from "../UI/i18n/Translations";
import {existsSync, mkdir, mkdirSync, writeFileSync} from "fs";
import {AllKnownLayouts} from "../Customizations/AllKnownLayouts";
import TableOfContents from "../UI/Base/TableOfContents";
import SimpleMetaTaggers, {SimpleMetaTagger} from "../Logic/SimpleMetaTagger";
import ValidatedTextField from "../UI/Input/ValidatedTextField";
import LayoutConfig from "../Models/ThemeConfig/LayoutConfig";
import SpecialVisualizations from "../UI/SpecialVisualizations";
import FeatureSwitchState from "../Logic/State/FeatureSwitchState";
import {ExtraFunctions} from "../Logic/ExtraFunctions";
import Title from "../UI/Base/Title";
import Minimap from "../UI/Base/Minimap";
import {QueryParameters} from "../Logic/Web/QueryParameters";
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
}


const dummyLayout = new LayoutConfig({
    id: "&gt;theme&lt;",
    maintainer: "pietervdvn",
    version: "0",
    title: {en:"<theme>"},
    description: "A theme to generate docs with",
    socialImage: "./assets/SocialImage.png",
    startLat: 0,
    startLon: 0,
    startZoom: 0,
    icon: undefined,
    layers: [
        {
            name: "<layer>",
            id: "&lt;layer&gt;",
            source: {
                osmTags: "id~*"
            },
            mapRendering: null,
        }
    ]

})

new FeatureSwitchState(dummyLayout)

QueryParameters.GetQueryParameter("layer-&lt;layer-id&gt;", "true", "Wether or not the layer with id <layer-id> is shown")

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

console.log("Generated docs")