Scaffold.pudu

Pudu52 lines3.1 KB

Copy pathGitHub ↗

1/** @Docgen.Scaffold.Module — the files of a new documentation project */2module PuduLangDocgen.Scaffold34import Std.Json as Json5import PuduLangDocgen.Yaml as Yaml67/** @Docgen.Scaffold.Answers — choices that shape a new project */8export type Answers = { title: Str, api: Bool, sources: Str, output: Str, pdf: Bool }910/// Choices used when nothing is asked: a site titled after its folder with an API section.11export fn defaults(title: Str) -> Answers {12  Answers{title: if title.isEmpty() { "Documentation" } else { title }, api: true, sources: "src", output: "_site", pdf: false}13}1415/// Every file of a new project by relative path.16export fn files(answers: &Answers) -> Array[(Str, Str)] {17  var navigation = [("Home", "index.md"), ("Guide", "docs/")]18  if answers.api { navigation = navigation.push(("API", "api/")) }19  var result = [20    ("docgen.json", config(answers)),21    ("index.md", "---\ntitle: " + Yaml.scalar(answers.title) + "\n_layout: landing\n---\n\n# " + answers.title + "\n\nWelcome. Start with the [introduction](docs/introduction.md)" + (if answers.api { " or open **API** in the navigation bar." } else { "." }) + "\n"),22    ("toc.yml", navigation.map(fn(entry: (Str, Str)) -> Str {23          let (name, href) = entry24          "- name: " + name + "\n  href: " + href25        }).join("\n") + "\n"),26    ("docs/introduction.md", "# Introduction\n\nDescribe what the project does and who it is for.\n\n> [!TIP]\n> Every page is Markdown. Headings build the outline on the right.\n"),27    ("docs/getting-started.md", "# Getting started\n\n## Install\n\nExplain how to install the project.\n\n## First steps\n\nWalk through a first task.\n"),28    ("docs/toc.yml", "- name: Introduction\n  href: introduction.md\n- name: Getting started\n  href: getting-started.md\n"),29    (".gitignore", answers.output + "/\n.docgen/\n")30  ]31  if answers.api && answers.sources == "src" {32    result = result.push(("src/Example.pudu", "/** @Example.Module — replace with the modules to document */\nmodule Example\n\n/// A greeting for a name.\nexport fn greet(name: Str) -> Str \{ \"Hello, \" + name \}\n"))33  }34  result35}3637/// The configuration of a new project.38fn config(answers: &Answers) -> Str {39  let build = [40    ("content", Json.list(&[Json.object(&[("files", Json.list(&[Json.Text("**/*.md"), Json.Text("**/toc.yml")])), ("exclude", Json.list(&[Json.Text(answers.output + "/**"), Json.Text("api/**")]))])])),41    ("resource", Json.list(&[Json.object(&[("files", Json.list(&[Json.Text("images/**")]))])])),42    ("output", Json.Text(answers.output)),43    ("template", Json.list(&[Json.Text("default")])),44    ("globalMetadata", Json.object(&[("_appTitle", Json.Text(answers.title)), ("_appName", Json.Text(answers.title)), ("_enableSearch", Json.Boolean(true)), ("pdf", Json.Boolean(answers.pdf))]))45  ]46  var top: Array[(Str, Json.Json)] = []47  if answers.api {48    top = top.push(("metadata", Json.list(&[Json.object(&[("src", Json.list(&[Json.object(&[("files", Json.list(&[Json.Text("**/*.pudu")])), ("src", Json.Text(answers.sources))])])), ("dest", Json.Text("api"))])])))49  }50  Json.encodePretty(&Json.object(&top.push(("build", Json.object(&build))))) + "\n"51}52