Docs: improve documentation with quick overview table of the most important questions

scripts/generateLayerOverview.ts

@@ -406,6 +406,7 @@ class LayerOverviewUtils extends Script {
 
         for (const tr of sharedQuestions.tagRenderings) {
             const tagRendering = <QuestionableTagRenderingConfigJson>tr
+            tagRendering._definedIn = ["questions", tr["id"]]
             dict.set(tagRendering["id"], tagRendering)
         }
 

src/Models/ThemeConfig/Conversion/ExpandTagRendering.ts

@@ -62,7 +62,7 @@ export class ExpandTagRendering extends Conversion<
         spec: string | { builtin: string | string[] } | TagRenderingConfigJson,
         ctx: ConversionContext
     ): QuestionableTagRenderingConfigJson[] {
-        const trs = this.convertOnce(<any>spec, ctx)?.map((tr) =>
+        const trs = this.convertOnce(spec, ctx)?.map((tr) =>
             this.pruneMappings<TagRenderingConfigJson & { id: string }>(tr, ctx)
         )
         if (!Array.isArray(trs)) {
@@ -231,6 +231,8 @@ export class ExpandTagRendering extends Conversion<
                 }
             }
 
+            found._definedIn = [layer.id, found.id]
+
             found = contextWriter.convertStrict(
                 found,
                 ConversionContext.construct(
@@ -248,9 +250,9 @@ export class ExpandTagRendering extends Conversion<
     }
 
     private convertOnce(
-        tr: string | { builtin: string } | TagRenderingConfigJson,
+        tr: string | { builtin: string | string[] } | TagRenderingConfigJson,
         ctx: ConversionContext
-    ): TagRenderingConfigJson[] {
+    ): (TagRenderingConfigJson & { id: string })[] {
         const state = this._state
 
         if (tr === undefined) {

src/Models/ThemeConfig/Conversion/PrepareLayer.ts

@@ -1,18 +1,6 @@
-import {
-    Concat,
-    DesugaringContext,
-    DesugaringStep,
-    Each,
-    FirstOf,
-    Fuse,
-    On,
-    SetDefault,
-} from "./Conversion"
+import { Concat, DesugaringContext, DesugaringStep, Each, FirstOf, Fuse, On, SetDefault } from "./Conversion"
 import { LayerConfigJson } from "../Json/LayerConfigJson"
-import {
-    MinimalTagRenderingConfigJson,
-    TagRenderingConfigJson,
-} from "../Json/TagRenderingConfigJson"
+import { MinimalTagRenderingConfigJson, TagRenderingConfigJson } from "../Json/TagRenderingConfigJson"
 import { Utils } from "../../../Utils"
 import RewritableConfigJson from "../Json/RewritableConfigJson"
 import SpecialVisualizations from "../../../UI/SpecialVisualizations"
@@ -265,6 +253,7 @@ export class AddQuestionBox extends DesugaringStep<LayerConfigJson> {
             seen.add("hidden")
             const question: QuestionableTagRenderingConfigJson = {
                 id: "leftover-questions",
+                labels: ["ignore-docs", "added_by_default"],
                 render: {
                     "*": `{questions( ,${Array.from(seen).join(";")})}`,
                 },

src/Models/ThemeConfig/Json/TagRenderingConfigJson.ts

@@ -228,4 +228,10 @@ export interface TagRenderingConfigJson {
      * This tagRendering can introduce this builtin filter
      */
     filter?: string[] | true
+
+    /**
+     * Helper to indicate where the tagRendering was originally defined
+     * group: hidden
+     */
+    _definedIn?: [string, string]
 }

src/Models/ThemeConfig/LayerConfig.ts

@@ -376,6 +376,59 @@ export default class LayerConfig extends WithContextLoader {
         return this.mapRendering.some((r) => r.location.has("point"))
     }
 
+    /**
+     * A quick overview table of all the elements in the popup-box
+     * @private
+     */
+    private generateDocumentationQuickTable(): string {
+
+
+        return MarkdownUtils.table(
+            ["id", "question", "labels", "freeform key"],
+            this.tagRenderings
+                .filter(tr => tr.labels.indexOf("ignore_docs") < 0)
+                .map(tr => {
+
+                    let key = "_Multiple choice only_"
+                    if (tr.freeform) {
+                        const type = `[${tr.freeform.type}](../SpecialInputElements.md#${tr.freeform.type})`
+
+                        key = `*[${tr.freeform.key}](https://wiki.osm.org/wiki/Key:${tr.freeform.key})* (${type})`
+                    }
+                    let origDef = ""
+                    if (tr._definedIn) {
+                        let [layer, id] = tr._definedIn
+                        if (layer == "questions") {
+                            layer = "./BuiltinQuestions"
+                        } else {
+                            layer = "./" + layer
+                        }
+                        origDef = `<br/> _(Original in [${tr._definedIn[0]}](${layer}.md#${id}))_`
+                    }
+                    const q = tr.question?.Subs(this.baseTags)?.txt?.trim()
+                    let r = tr.render?.txt
+                    if (r && r !== "") {
+                        r = `_${r}_`
+                    }
+                    let options: string = undefined
+                    if (tr.mappings?.length > 0) {
+                        options = `${tr.mappings.length} options`
+                    }
+
+                    return [
+                        `[${tr.id}](#${tr.id}) ${origDef}`,
+                        Utils.NoNull([q, r, options]).join("<br/>"),
+                        tr.labels.join(", "),
+                        key
+
+                    ]
+
+
+                })
+        )
+
+    }
+
     public generateDocumentation(
         usedInThemes: string[],
         layerIsNeededBy?: Map<string, string[]>,
@@ -530,8 +583,7 @@ export default class LayerConfig extends WithContextLoader {
         let quickOverview: string[] = []
         if (tableRows.length > 0) {
             quickOverview = [
-                "**Warning:**",
-                "this quick overview is incomplete",
+                "**Warning:**: this quick overview is incomplete",
                 MarkdownUtils.table(
                     ["attribute", "type", "values which are supported by this layer"],
                     tableRows
@@ -603,7 +655,9 @@ export default class LayerConfig extends WithContextLoader {
             ...presets,
             ...tagsDescription,
             "## Supported attributes",
-            quickOverview,
+            ...quickOverview,
+            "## Featureview elements and TagRenderings",
+            this.generateDocumentationQuickTable(),
             ...this.tagRenderings
                 .filter((tr) => tr.labels.indexOf("ignore_docs") < 0)
                 .map((tr) => tr.GenerateDocumentation()),

src/Models/ThemeConfig/TagRenderingConfig.ts

@@ -60,6 +60,11 @@ export default class TagRenderingConfig {
 
     public readonly configuration_warnings: string[] = []
 
+    /**
+     * States where this was originally defined, if imported
+     */
+    public readonly _definedIn: [string, string] = undefined
+
     public readonly freeform?: {
         readonly key: string
         readonly type: ValidatorType
@@ -147,6 +152,7 @@ export default class TagRenderingConfig {
         this.questionHintIsMd = json["questionHintIsMd"] ?? false
         this.alwaysForceSaveButton = json["#force-save-button"] === "yes"
         this.description = Translations.T(json.description, translationKey + ".description")
+        this._definedIn = json._definedIn
         if (json.onSoftDelete && !Array.isArray(json.onSoftDelete)) {
             throw context + ".onSoftDelete Not an array: " + typeof json.onSoftDelete
         }