mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-09 23:27:43 +02:00
Enterprise Docs (#2390)
* install VuePress Plugin Tabs https://www.npmjs.com/package/vuepress-plugin-tabs * init Enterprise documentation section * replace Vuepress tab plugin now using https://github.com/superbiger/vuepress-plugin-tabs * init Enterprise Quickstart * block of enterprise doc updates * Helm Quickstart Update (#2380) * removed/fixed redundant or incorrect config And some small copy edits * Update docs/docs/quick-start/helm.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * init console with helm doc * squash me * codeblock fix * init about page * updates to Enterprise section * consolidate on Postgres * WIP helm updates * update and align OS and Enterprise helm docs * Enterprise settings docs (#2397) * init console-specific reference docs files * remove shortdoc for name * init Enterprise Reference doc * expanding Enterprise Reference * init JS script for reference subpages When reviewing please remember that I'm not a developer, be kind * update script and apply * remove errant dep * document script and expand for CLI help output * import pomerium-console_serve.yaml In future iterations, this file should be sourced at build time as an artifact from the pomerium-console repo * init new output file * update script call and output * fix anchor links * BROKEN - import content from settings.yaml when dupe is true * filtering WiP * fix dupe script, more content * replace if dupe with if not docs * squash me * squash me! * add docs about PPL (#2404) * squash meeeeee * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * symlink img dir from docs/reference * squash mee * update install reqs * Fixed links throughout * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/install/quickstart.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * remove internal note * - format python with black - format js with prettier Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * optimize images with imageOptim Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * run prettier on config.js Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * concepts.md Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * update concepts Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com> * copy edits * typo * symlink img dir from docs/reference * modify TLS section in quick-start * rm whitespace * add common links postamble * block of updates * block of updates * updates with @travisgroth * turtles all the way down * more content * import all the things * fill out reports * fill out reports * fix file extension * fix links * crosslink PPL ref * document embedded prometheus * expand example * update reqs * document non-directory users * typo fix * update metrics_address * fix broken links in example configs * update examples for route syntax * replaced required with deprecated Note that I didn't link to the route reference because I'm unsure what link formats are accepted when this file is used elsewhere. The warning block below includes a link. * update enterprise/about * Update docs/enterprise/console-settings.yaml Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/console-settings.yaml Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * remove commented config lines * update non-domain user section in concepts * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/about.md Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * Update docs/enterprise/concepts.md Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> * add console route to OSS conf * update enterprise settings copy from source file * Update docs/enterprise/concepts.md * Update reports reference * merge conflict resolution * update sourced doc content, fix whitespace Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com> Co-authored-by: Caleb Doxsey <cdoxsey@pomerium.com> Co-authored-by: Bobby DeSimone <bobbydesimone@gmail.com> Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
This commit is contained in:
Alex Fornuto
GitHub
parent
0b9f06b5ae
commit
5332a752d0
72 changed files with 2775 additions and 217 deletions
172
scripts/generate-console-pages.js
Executable file
172
scripts/generate-console-pages.js
Executable file
|
|
@ -0,0 +1,172 @@
|
|||
// generate-console-pages.js
|
||||
|
||||
const fs = require("fs");
|
||||
const yaml = require("js-yaml");
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
|
||||
// Functions
|
||||
|
||||
/**
|
||||
*
|
||||
* Import content from /docs/reference/settings.yaml when needed.
|
||||
*/
|
||||
const fromOSSettings = (name, keys) => {
|
||||
//console.log(keys)
|
||||
const asMap = Object.values(OSSettings.settings).map((section) => {
|
||||
const subSections = Object.values(section.settings)
|
||||
return subSections
|
||||
} )
|
||||
let result = ''
|
||||
for (let i = 0; i < asMap.length; i++ ) {
|
||||
for (j = 0; j < asMap[i].length; j++){
|
||||
const fixAnchorLinksRegex = /\(\#/g
|
||||
const fixHTMLLinksRegex = /\(\/(.+?).html/g
|
||||
if (asMap[i][j].name === name) {
|
||||
result = asMap[i][j].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
else if (keys !== null && asMap[i][j].keys && keys.some( key => asMap[i][j].keys.indexOf(key) >= 0)) {
|
||||
result = asMap[i][j].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
} else {
|
||||
if (asMap[i][j].settings) {
|
||||
for (k = 0; k < asMap[i][j].settings.length; k++) {
|
||||
if (asMap[i][j].settings[k].name === name && asMap[i][j].settings[k].doc) {
|
||||
result = asMap[i][j].settings[k].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
else if (keys !== null && asMap[i][j].settings[k].keys && keys.some( key => asMap[i][j].settings[k].keys.indexOf(key) >= 0) && asMap[i][j].settings[k].doc) {
|
||||
result = asMap[i][j].settings[k].doc.replace(fixAnchorLinksRegex, "(/reference/readme.md#").replace(fixHTMLLinksRegex, "(/$1.md")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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) => {
|
||||
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
|
||||
meta:
|
||||
- name: keywords
|
||||
content: configuration options settings Pomerium enterprise console
|
||||
---
|
||||
|
||||
`;
|
||||
|
||||
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 + postamble;
|
||||
|
||||
fs.writeFileSync(path, content);
|
||||
};
|
||||
|
||||
/**
|
||||
* Called by writePage, this function
|
||||
* handles nested settings objects.
|
||||
*/
|
||||
const writeSubsection = (subsection, depth) => {
|
||||
let subContent = "";
|
||||
if (!subsection.name) {
|
||||
return;
|
||||
}
|
||||
if (!subsection.doc) {
|
||||
//console.log(subsection)
|
||||
//console.log(subsection.keys || "no key")
|
||||
subContent =
|
||||
fromOSSettings(subsection.name, subsection.keys || null) + "\n";
|
||||
}
|
||||
let header = "#".repeat(depth) + " " + subsection.name + "\n" + "\n";
|
||||
subContent =
|
||||
subContent + (subsection.doc ? subsection.doc.toString() + "\n\n" : "");
|
||||
subsection.attributes
|
||||
? (subContent = subContent + subsection.attributes.toString())
|
||||
: null;
|
||||
subsection.settings
|
||||
? (subContent =
|
||||
subContent +
|
||||
subsection.settings
|
||||
.map((turtles) => writeSubsection(turtles, depth + 1))
|
||||
.join(""))
|
||||
: "";
|
||||
return header + subContent;
|
||||
};
|
||||
|
||||
// Main
|
||||
|
||||
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")
|
||||
);
|
||||
let OSSettings = yaml.load(
|
||||
fs.readFileSync("./docs/reference/settings.yaml", "utf8")
|
||||
);
|
||||
let postamble = docs.postamble
|
||||
|
||||
writeConfigPage(keysFile);
|
||||
|
||||
docs.settings.map((setting) => {
|
||||
writePage(setting);
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue