import Combine from "../UI/Base/Combine" import BaseUIElement from "../UI/BaseUIElement" 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" import { writeFile } from "fs" import Translations from "../UI/i18n/Translations" import themeOverview from "../assets/generated/theme_overview.json" import DefaultGUI from "../UI/DefaultGUI" import FeaturePipelineState from "../Logic/State/FeaturePipelineState" import LayoutConfig from "../Models/ThemeConfig/LayoutConfig" import bookcases from "../assets/generated/themes/bookcases.json" import { DefaultGuiState } from "../UI/DefaultGuiState" import fakedom from "fake-dom" import Hotkeys from "../UI/Base/Hotkeys" import { QueryParameters } from "../Logic/Web/QueryParameters" import Link from "../UI/Base/Link" import Constants from "../Models/Constants" import LayerConfig from "../Models/ThemeConfig/LayerConfig" import DependencyCalculator from "../Models/ThemeConfig/DependencyCalculator" import { AllSharedLayers } from "../Customizations/AllSharedLayers" 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") if (!md.endsWith("\n")) { md += "\n" } const warnAutomated = "[//]: # (WARNING: this file is automatically generated. Please find the sources at the bottom and edit those sources)" writeFileSync(filename, warnAutomated + md) } function GenerateDocumentationForTheme(theme: LayoutConfig): BaseUIElement { return new Combine([ new Title( new Combine([ theme.title, "(", new Link(theme.id, "https://mapcomplete.osm.be/" + theme.id), ")", ]), 2 ), theme.description, "This theme contains the following layers:", new List( theme.layers .filter((l) => !l.id.startsWith("note_import_")) .map((l) => new Link(l.id, "../Layers/" + l.id + ".md")) ), "Available languages:", new List(theme.language.filter((ln) => ln !== "_context")), ]).SetClass("flex flex-col") } /** * Generates the documentation for the layers overview page * @constructor */ function GenLayerOverviewText(): BaseUIElement { for (const id of Constants.priviliged_layers) { if (!AllSharedLayers.sharedLayers.has(id)) { throw "Priviliged layer definition not found: " + id } } const allLayers: LayerConfig[] = Array.from(AllSharedLayers.sharedLayers.values()).filter( (layer) => Constants.priviliged_layers.indexOf(layer.id) < 0 ) const builtinLayerIds: Set = new Set() allLayers.forEach((l) => builtinLayerIds.add(l.id)) const themesPerLayer = new Map() for (const layout of Array.from(AllKnownLayouts.allKnownLayouts.values())) { for (const layer of layout.layers) { if (!builtinLayerIds.has(layer.id)) { continue } if (!themesPerLayer.has(layer.id)) { themesPerLayer.set(layer.id, []) } themesPerLayer.get(layer.id).push(layout.id) } } // Determine the cross-dependencies const layerIsNeededBy: Map = new Map() for (const layer of allLayers) { for (const dep of DependencyCalculator.getLayerDependencies(layer)) { const dependency = dep.neededLayer if (!layerIsNeededBy.has(dependency)) { layerIsNeededBy.set(dependency, []) } layerIsNeededBy.get(dependency).push(layer.id) } } return new Combine([ new Title("Special and other useful layers", 1), "MapComplete has a few data layers available in the theme which have special properties through builtin-hooks. Furthermore, there are some normal layers (which are built from normal Theme-config files) but are so general that they get a mention here.", new Title("Priviliged layers", 1), new List(Constants.priviliged_layers.map((id) => "[" + id + "](#" + id + ")")), ...Constants.priviliged_layers .map((id) => AllSharedLayers.sharedLayers.get(id)) .map((l) => l.GenerateDocumentation( themesPerLayer.get(l.id), layerIsNeededBy, DependencyCalculator.getLayerDependencies(l), Constants.added_by_default.indexOf(l.id) >= 0, Constants.no_include.indexOf(l.id) < 0 ) ), new Title("Normal layers", 1), "The following layers are included in MapComplete:", new List( Array.from(AllSharedLayers.sharedLayers.keys()).map( (id) => new Link(id, "./Layers/" + id + ".md") ) ), ]) } /** * Generates documentation for the layers. * Inline layers are included (if the theme is public) * @param callback * @constructor */ function GenOverviewsForSingleLayer( callback: (layer: LayerConfig, element: BaseUIElement, inlineSource: string) => void ): void { const allLayers: LayerConfig[] = Array.from(AllSharedLayers.sharedLayers.values()).filter( (layer) => Constants.priviliged_layers.indexOf(layer.id) < 0 ) const builtinLayerIds: Set = new Set() allLayers.forEach((l) => builtinLayerIds.add(l.id)) const inlineLayers = new Map() for (const layout of Array.from(AllKnownLayouts.allKnownLayouts.values())) { if (layout.hideFromOverview) { continue } for (const layer of layout.layers) { if (Constants.priviliged_layers.indexOf(layer.id) >= 0) { continue } if (builtinLayerIds.has(layer.id)) { continue } if (layer.source.geojsonSource !== undefined) { // Not an OSM-source continue } allLayers.push(layer) builtinLayerIds.add(layer.id) inlineLayers.set(layer.id, layout.id) } } const themesPerLayer = new Map() for (const layout of Array.from(AllKnownLayouts.allKnownLayouts.values())) { if (layout.hideFromOverview) { continue } for (const layer of layout.layers) { if (!builtinLayerIds.has(layer.id)) { // This is an inline layer continue } if (!themesPerLayer.has(layer.id)) { themesPerLayer.set(layer.id, []) } themesPerLayer.get(layer.id).push(layout.id) } } // Determine the cross-dependencies const layerIsNeededBy: Map = new Map() for (const layer of allLayers) { for (const dep of DependencyCalculator.getLayerDependencies(layer)) { const dependency = dep.neededLayer if (!layerIsNeededBy.has(dependency)) { layerIsNeededBy.set(dependency, []) } layerIsNeededBy.get(dependency).push(layer.id) } } allLayers.forEach((layer) => { const element = layer.GenerateDocumentation( themesPerLayer.get(layer.id), layerIsNeededBy, DependencyCalculator.getLayerDependencies(layer) ) callback(layer, element, inlineLayers.get(layer.id)) }) } /** * The wikitable is updated as some tools show an overview of apps based on the wiki. */ function generateWikipage() { function generateWikiEntry(layout: { hideFromOverview: boolean id: string shortDescription: any }) { if (layout.hideFromOverview) { return "" } const languagesInDescr = Array.from(Object.keys(layout.shortDescription)).filter( (k) => k !== "_context" ) const languages = languagesInDescr.map((ln) => `{{#language:${ln}|en}}`).join(", ") let auth = "Yes" return `{{service_item |name= [https://mapcomplete.osm.be/${layout.id} ${layout.id}] |region= Worldwide |lang= ${languages} |descr= A MapComplete theme: ${Translations.T(layout.shortDescription) .textFor("en") .replace(".*<\/a>/, "]]")} |material= {{yes|[https://mapcomplete.osm.be/ ${auth}]}} |image= MapComplete_Screenshot.png |genre= POI, editor, ${layout.id} }}` } let wikiPage = '{|class="wikitable sortable"\n' + "! Name, link !! Genre !! Covered region !! Language !! Description !! Free materials !! Image\n" + "|-" for (const layout of themeOverview) { if (layout.hideFromOverview) { continue } wikiPage += "\n" + generateWikiEntry(layout) } wikiPage += "\n|}" writeFile("Docs/wikiIndex.txt", wikiPage, (err) => { if (err !== null) { console.log("Could not save wikiindex", err) } }) } console.log("Starting documentation generation...") ScriptUtils.fixUtils() generateWikipage() 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 }) }) Array.from(AllKnownLayouts.allKnownLayouts.values()).map((theme) => { const docs = GenerateDocumentationForTheme(theme) WriteFile( "./Docs/Themes/" + theme.id + ".md", docs, [`assets/themes/${theme.id}/${theme.id}.json`], { 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", 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() var layersUsingBuiltin = new Map() 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", ]) if (fakedom === undefined || window === undefined) { throw "FakeDom not initialized" } QueryParameters.GetQueryParameter( "mode", "map", "The mode the application starts in, e.g. 'map', 'dashboard' or 'statistics'" ) new DefaultGUI( new FeaturePipelineState(new LayoutConfig(bookcases)), new DefaultGuiState() ).setup() WriteFile("./Docs/Hotkeys.md", Hotkeys.generateDocumentation(), []) console.log("Generated docs")