support deprecated options

#refactor

Author: alandefreitas

docs/extensions/config-options-reference.js

@@ -90,6 +90,10 @@ function toDefaultValueStr(value) {
 }
 
 function pushOptionBlocks(options, block, parents = []) {
+    function makeOptionID(option) {
+        return [...parents, option.name].join('_') + "_option"
+    }
+
     block.lines.push('<table class="tableblock frame-all grid-all stretch">')
     block.lines.push('<colgroup>')
     block.lines.push('<col style="width: 23.3333%;">')
@@ -108,7 +112,8 @@ function pushOptionBlocks(options, block, parents = []) {
         let optionName = [...parents, option.name].join('.')
         block.lines.push('<tr>')
         block.lines.push(`<td class="tableblock halign-left valign-top">`)
-        block.lines.push(`<code style="color: darkblue">${optionName}</code>`)
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<a href="#${makeOptionID(option)}"><code style="color: ${colorStr}">${optionName}</code></a>`)
         block.lines.push(`<br/>`)
         block.lines.push(`<span style="color: darkgreen;">(${toTypeStr(option.type)})</span>`)
         let observations = []
@@ -118,8 +123,11 @@ function pushOptionBlocks(options, block, parents = []) {
         if (option['command-line-only']) {
             observations.push('Command line only')
         }
+        if (option['deprecated']) {
+            observations.push(`Deprecated`)
+        }
         if (observations.length !== 0) {
-            block.lines.push(`<br/><br/>`)
+            block.lines.push(`<br/>`)
             let observationsStr = observations.join(', ')
             block.lines.push(`<span style="color: orangered;">(${observationsStr})</span>`)
         }
@@ -134,14 +142,19 @@ function pushOptionBlocks(options, block, parents = []) {
     // Option details
     for (let option of options) {
         let optionName = [...parents, option.name].join('.')
-        block.lines.push(`<div class="paragraph"><p><b><code style="color: darkblue">${optionName}</code></b></p></div>`)
+        const optionID = optionName.replace(/\./g, '_')
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<div class="paragraph" id="${makeOptionID(option)}"><p><b><code style="color: ${colorStr}">${optionName}</code></b></p></div>`)
         block.lines.push(`<div class="paragraph"><p><i>${option.brief}</i></p></div>`)
         if (option.details) {
             block.lines.push(`<div class="paragraph"><p>${replaceCodeTags(escapeHtml(option.details))}</p></div>`)
         }
         block.lines.push(`<div class="paragraph"><p>`)
         block.lines.push(`<div class="ulist">`)
         block.lines.push(`<ul>`)
+        if (option['deprecated']) {
+            block.lines.push(`<li><span style="color: red;">Deprecated</span>: ${replaceCodeTags(escapeHtml(option['deprecated']))}</li>`)
+        }
         if (option.type) {
             block.lines.push(`<li>Type: ${toTypeStr(option.type)}</li>`)
         } else {

util/generate-config-info.py

@@ -393,6 +393,7 @@ def generate_public_settings_hpp(config):
         contents += f'            {cpp_type}'
     contents += f'> {to_camel_case("default")}Value = std::monostate();\n'
     contents += f'        std::string {to_camel_case("relative-to")} = {{}};\n'
+    contents += f'        std::optional<std::string> {to_camel_case("deprecated")} = std::nullopt;\n'
     contents += '    };\n\n'
 
     contents += '    /** Normalize the configuration values with a visitor\n'
@@ -441,6 +442,8 @@ def generate_public_settings_hpp(config):
                 contents += f'{pad}.{to_camel_case("default")}Value = {cpp_type}({cpp_default_value}),\n'
         if 'relative-to' in option:
             contents += f'{pad}.{to_camel_case("relative-to")} = {escape_as_cpp_string(option["relative-to"])},\n'
+        if 'deprecated' in option:
+            contents += f'{pad}.{to_camel_case("deprecated")} = {escape_as_cpp_string(option["deprecated"])},\n'
         contents += f'        }}));\n'
     contents += '        return {};\n'
     contents += '    }\n\n'