github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/utils/docgen/README.md (about) 1 # docgen 2 3 ## `docgen` is a tool for auto-generating technical documents 4 5 The purpose of this tool is to automate documentation as 6 much as possible and have the output a static CMS which 7 can be hosted on GitHub or S3 (depending on whether your 8 templates are markdown or HTML). 9 10 It was written originally for the Murex project (https://github.com/lmorg/murex) 11 however it is flexible enough to be useful in other projects 12 as well. 13 14 All config if defined in YAML files and template files 15 (using the templating engine from Go's (golang) core libs) 16 17 ## Usage 18 19 docgen -config docgen.yaml 20 21 ## Flags 22 23 -config takes a string parameter for a path to a YAML file 24 -verbose optional flag to enable log and warning messages 25 -warning optional flag to enable warning messages 26 -panic optional flag to enable stack a trace on error 27 -readonly optional flag to prevent files getting written to disk 28 (use -readonly to test your config, templates, etc) 29 30 ## Don't Panic! 31 32 You may notice there are a lot of `panic()`'s in the codebase. 33 This is deliberate because by we want any errors to fail the 34 utility (essentially raising all errors as exceptions). However 35 the panics are caught in `main()` by default (ie if `-panic` 36 isn't set) so you get friendly error messages as standard but a 37 stack trace on all errors for debugging if needed. 38 39 I get this isn't the typical Go idiom but it makes more sense 40 for this particular application given it serves one function 41 and any errors beyond that should fail the program.