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.