crash when trying on test yaml file

[talwgx]

Testing on a .yaml containing the following content (file renamed to .txt for upload to GH)

logMethods copy.txt

produced the following error:

Configuration Parameters Reference

Any information about this page goes here.

Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.9/bin/yamldoc", line 8, in
sys.exit(cli())
File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/yamldoc/cli.py", line 14, in cli
yamldoc.main(args.file, args.char, args.debug, args.schema)
File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/yamldoc/parser.py", line 413, in main
yaml = parse_yaml(yaml_path, char, debug)
File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/yamldoc/parser.py", line 43, in parse_yaml
key, value = line.rstrip().split(":", 1)
ValueError: not enough values to unpack (expected 2, got 1)

[Christopher Cole]

Hi, thanks very much for the report. Would you mind letting me know which version of yamldoc you are using? The one on pypi is quite a bit behind the master branch here.

Do you mind if I ask where you got this file from as well? I don't know if I've included the case of a list on the top level as you have here (three lines starting with - name but without an identifier).

yamllint (https://www.yamllint.com/) shows that your file is valid YAML, it might just be a bit more complicated than I've included coverage for.

The comments should all be ignored by the way, so a clean version for testing would look like:

---
- names:
    - logMethods
  description: names of source code methods that are considered to be logging
    methods (e.g. 'error')
  type: list
  required: false
- names:
    - logMethodRegex
  description: pattern that source code methods that are considered to be logging
    methods must match (e.g. '^(log|Log)|(Log|log)$')
  type: string
  required: false
- names:
    - logStreams
  description: names of source code variables who are considered to be logging
    streams (e.g. 'cerr')
  type: list
  required: false

[talwgx]

Version - i ran ' pip install yamldoc' (on OSX) based on the instructions from website - so that's the ver used.

File - it's part of our application, it was just the first one I grabbed (we have many like it). The project looks great so I wanted to recommend we use it to doc our .yamls. Be great if we could make it happen. Thanks!

[Christopher Cole]

I see, that makes sense. I will look into the specifics of your use case, but while I'm doing that I wanted to provide a stopgap solution as well.

I would recommend a few things based on your file:

• The title and description that you are providing won't be respected by yamldoc naively, they must be placed in special _yamldoc_title and _yamldoc_description objects in a schema file. This basically just sets the title and the description of the page.
• The - name: - logMethod syntax is a little strange (though I'm sure reasonable in your application), could you possible refactor to have just the object named logMethod followed by its attributes? That would be recommended from the yamldoc use case.
• I would also recommend moving the type attribute into the same schema file used for the title and descriptions. I don't have support for a special type attribute in the raw document. It has to be in a separate file.
• Your comments right now do not use any special syntax to indicate that they should be included by yamldoc in the resulting file. If you take a quick look at the Flat YAML section of the tutorial it explains the distinction: https://chrisbcole.me/yamldoc/tutorial/ but basically you have to start them with #' instead of #.
• Note that you have to escape some special characters in the second description, because | is the tab separator in markdown for tables.

As an illustrative example, I've reformatted your input so that it works with yamldoc as-is without any modifications.

The logMethods.yaml file would look like:

#' 'logMethods' lists known method names collected from common logging
#'  frameworks used to indicate source code that is logging event data to stream.
logMethods: 
  description: "names of source code methods that are considered to be logging methods (e.g. 'error')"
  type: list
  required: false

#' 'logMethodRegex' specifies an optional regex that will be applied
#'  to a scanned source code method/function name. If matched, the method
#'  will be considered to be a 'logging method' (see above). For example: ^(log|Log)|(Log|log)$
logMethodRegex:
  description: "pattern that source code methods that are considered to be logging methods must match (e.g. '^(log\|Log)\|(Log\|log)$')"
  type: string
  required: false

#' 'logStreams' defines which source code variables within 
#'  this ANTLR syntax are treated as output streams (e.g. stdout, stderr).
#'  Literal constants (e.g. "error connecting to {}") passed to a variable 
#'  listed below (e.g 'cout') will be assigned a 'logger_method_invoke' 
#'  symbol source context. 
logStreams:
  description: "names of source code variables who are considered to be logging streams (e.g. 'cerr')"
  type: list
  required: false

And the special logMethods.schema file that I mentioned above would look like:

# These are special options that 
# control the output markdown document.
_yamldoc_title: 🔟❎ 'compile' log methods options
_yamldoc_description: log Methods options define input source code method name that if found to be called within a function located inside scanned source code file will mark the symbol context of any string constant passed to them as 'logger_method_invoke' within output symbol unit produced for that source code file. Identifying points in input source code that perform logging operations allows the 'run' pipeline to correlate l1x Objects read from a target input back to the source code from which they originated.

This gives the Markdown output shown below by using (note: the -s switch refers to the schema file):

yamldoc logMethods.yaml -s logMethods.schema

I'll attach the formatted markdown below that results from this. Note that I'm using the master branch here rather than the pip install version, I think it should work with that version as well though. Let me know if these refactoring changes are impossible and I can look into any of the specific changes that might be needed to help you out.

---

⚠️ The resulting markdown from the above command follows ⚠️

---

🔟❎ 'compile' log methods options

log Methods options define input source code method name that if found to be called within a function located inside scanned source code file will mark the symbol context of any string constant passed to them as 'logger_method_invoke' within output symbol unit produced for that source code file. Identifying points in input source code that perform logging operations allows the 'run' pipeline to correlate l1x Objects read from a target input back to the source code from which they originated.

logMethods

'logMethods' lists known method names collected from common logging frameworks used to indicate source code that is logging event data to stream.

Member variables:

Key	Value	Type	Information
description	"names of source code methods that are considered to be logging methods (e.g. 'error')"	Unknown
type	list	Unknown
required	false	Unknown

logMethodRegex

to a scanned source code method/function name. If matched, the method will be considered to be a 'logging method' (see above). For example: ^(log|Log)|(Log|log)$

Member variables:

Key	Value	Type	Information
description	"pattern that source code methods that are considered to be logging methods must match (e.g. '^(log|Log)|(Log|log)$')"	Unknown
type	string	Unknown
required	false	Unknown

logStreams

this ANTLR syntax are treated as output streams (e.g. stdout, stderr). Literal constants (e.g. "error connecting to {}") passed to a variable listed below (e.g 'cout') will be assigned a 'logger_method_invoke' symbol source context.

Member variables:

Key	Value	Type	Information
description	"names of source code variables who are considered to be logging streams (e.g. 'cerr')"	Unknown
type	list	Unknown
required	false	Unknown

---

Generated by yamldoc v0.1.6 on 2023-08-10

[talwgx]

Thanks for the feedback!

Changing yaml structure: this doc is parsed by a jackson objectMapper as part of a much larger deserialization process where this file and many others like it are combined into a much larger configuration DOM which i was hoping to document using yamldoc :) .. so I can't refactor it :/

Comments - I can def do that!

Type property - this is a property of a java object that is read into it from the yaml via jackson's objectMapper. I can change its name - will that help?

Type info - I see it's "unknown" in the output you pasted. Q - can it not be inferred from the yaml itself?