diff --git a/scripts/generate-console-pages.js b/scripts/generate-console-pages.js index dd2e074db..7ec8d3c51 100755 --- a/scripts/generate-console-pages.js +++ b/scripts/generate-console-pages.js @@ -1,12 +1,65 @@ // generate-console-pages.js + +/** + * This helper script, run by the technical writers, (re)generates markdown + * documents for the Enterprise reference section. It assumes the existence + * of `console-settings.yaml`, to be sourced as a build artifact from + * pomerium/pomerium-console, and `pomerium-console_serve.yaml`, sourced from + * running `pomerium-console gendocs. + */ + const fs = require('fs'); const yaml = require('js-yaml'); // Functions + +/** + * Import console environment/config options from `pomerium-console_serve.yaml` + */ +const writeConfigPage = (src) => { + //console.log(`keys from src file: ` + JSON.stringify(src)) // For Debugging + let path = './docs/enterprise/reference/config.md' + console.log(`Generating environment variable docs...\n`) + let frontmatter = +`--- +title: Environment Variables +lang: en-US +meta: + - name: keywords + content: configuration options settings Pomerium enterprise console +--- + +# Pomerium Console Environment Variables + +The keys listed below can be applied in Pomerium Console's \`config.yaml\` file, or applied as environment variables (in uppercase, replacing \`-\` with \`_\`). + +` + const keySection = (obj) => { + //console.log(JSON.stringify(obj.name)) // For Debugging + let header = `## ` + obj.name + '\n\n' + let body = +`${obj.usage} + +**Default value:** \`${obj.default_value ? obj.default_value : `none`}\` +` + return header + body + } + + let content = frontmatter + src.options.map(section => keySection(section)).join('\n') + fs.writeFileSync(path, content) +} + + +/** + * Read `console-settings.yaml` and write markdown pages under `docs/enterprise/reference`. +*/ const writePage = (setting) => { - console.log('Generating ', setting.name, " page") - let frontmatter = `--- + let path = './docs/enterprise/reference/' + setting.name.replace(/\s/g, '-').toLowerCase() + ".md" + console.log('Generating', path, "page") + + let frontmatter = +`--- title: ${setting.name} lang: en-US sidebarDepth: 2 @@ -16,17 +69,19 @@ meta: --- ` - let path = './docs/enterprise/reference/' + setting.name.replace(/\s/g, '-').toLowerCase() + ".md" - console.log("path=", path) //For Debugging + let header = '# ' + setting.name + '\n' + '\n' let body = setting.doc ? setting.doc.toString() + '\n' : '' let moreBody = setting.settings ? setting.settings.map(subsection => writeSubsection(subsection, 2)).join('') : '' - let content = frontmatter + header + body + moreBody + fs.writeFileSync(path, content) } +/** + * Called by writePage, this function handles nested settings objects. + */ const writeSubsection = (subsection, depth) => { if (!subsection.name) { return @@ -43,6 +98,9 @@ const writeSubsection = (subsection, depth) => { console.log("Reading console-settings.yaml") let docs = yaml.load(fs.readFileSync('./docs/enterprise/console-settings.yaml', 'utf8')) +let keysFile = yaml.load(fs.readFileSync('./docs/enterprise/pomerium-console_serve.yaml', 'utf8')) + +writeConfigPage(keysFile) docs.settings.map( setting => { writePage(setting)