We are using YAML as a config file format and want to add comments to it that we can convert to documentation, in the same way that Sphinx Autodoc, Doxygen, or Roxygen (in R) work.
I'm aware of this take that suggests description should be an integral part of the YAML document: Documenting yaml
I disagree with this. Our YAML files are configuration, not data - our documentation should show how to change and adapt the YAML rather than describe what's in the YAML right now.
I found:
http://chrisbcole.me/yamldoc/
https://yamldocs.dev/
https://github.com/Jakski/sphinxcontrib-autoyaml
https://github.com/ted-dunstone/yaml2doc
Neither appears to be in very wide use, am I missing something?
Related
Here is an earlier discussion, which asks about - How to convert from application.properties to application.yml in Spring Boot?
The solutions discussed above work but there is a limitation with #comments.
Comments (#comments) in .properties file are not carried forward in to .yaml file after conversion.
So want to check if there is any tool (online/ide based/offline) that supports conversion with comments carried forward into .yaml file.
read each line of the properties file
keep track of the comments
put the grouped property in a data structure together with the comment
write the data structure to the YAML file
What is the value in adding YAML atop an Azure DevOps Wiki page's markdown, as supported by its markdown syntax: Syntax guidance for Markdown usage in Wiki, YAML tags?
It seems to offer nothing more than an alternative syntax with which to specify tables. Perhaps more elaborate tables but they'll only render atop the page. What am I missing?
As the introduction in the document,
Any file that contains a YAML block in a Wiki is processed by a table with one head and one row.
So, I think the value of YAML tags in the Wiki markdown is to convert the abstract YAML statements into a visual table on the Wiki page to increase readability and quick understanding.
Especially for a complex YAML block that may contain multiple items or multiple sub-items, the YAML tags should be very helpful.
[UPDATE]
I find an issue ticket (MicrosoftDocs/azure-devops-docs#9976) reported by another user on the GitHub repository "MicrosoftDocs/azure-devops-docs". This issue has reported a similar question.
And in this issue ticket, you also can see #amitkumariiit has given an explanation:
Yaml tags are used for general search engine optimisation. Our plan was to add the basic support for it first and then ingest this in the azure devops wiki search for optimise search. However we could not prioritise the search side of work.
If you need more detailed explanation, you can follow this issue ticket and add your comments to it.
I am going to propose my own answer. It just occurred to me that this is likely intended to replace markdown, not to be used with markdown. That is to say, to support documentation written purely in YAML. That could make some sense, add value for some, and explain why it's ONLY supported atop the page. You use it instead of the markdown, not with the markdown.
The documentation just doesn't make it clear why/how you might want to use this feature.
I have an anchor as follows:
helm-install
docker-flags: &my_docker_flags
- "--network host"
- "--env KUBECONFIG=/tmp/admin.conf"
- "--env HOME=${env.HOME}"
- "--volume ${env.KUBECONFIG}:/tmp/admin.conf:ro"
- "--volume ${env.PWD}:${env.PWD}"
- "--volume ${env.HOME}/.helm:${env.HOME}/.helm"
- "--volume
${var.docker_config_basepath}:${var.docker_config_basepath}"
later I want to do:
docker-flags:
<<: *my_docker_flags
- "--env K8_NAMESPACE=${env.K8_NAMESPACE}"
But, the last line is flagged as bad indentation of a mapping entry YAML
The YAML merge key <<, defined here, is a feature defined for outdated YAML 1.1. It has never been part of the spec and thus its implementation is optional. Lots of YAML implementations implemented it and it remains a feature even while they get updated for YAML 1.2, which doesn't define this feature.
As a „key“, it is not a special syntax feature. Instead, much like the scalar true, it gets interpreted as something special because of its content. Supporting implementations will treat it according to the linked specification when it occurs as key in a mapping.
However, a sequence like the one you are showing is a different data structure: It contains a sequence of items. There is no place to put a merge key here, so you cannot use this feature in a sequence.
Generally, YAML is not a data processing language. << was and is an exception to that, there are no other processing features – neither for merging sequences, nor for different operations you would expect from a data processing language, like e.g. concatenation of strings.
For this reason, lots of tools that heavily use YAML, such as Ansible or Helm, include some kind of template processing for their YAML input files. While far from perfect, templating is currently the most versatile way to do data processing in a YAML file.
If the tool that reads your YAML doesn't provide you with a templating engine, your only option is to pre-process the YAML file manually, for example using a simple templating engine like mustache. Whether that is feasible depends of course on the context.
I would like to separate each change of the databaseChangeLog in YAML format into its own file (again YAML) and include/import it somehow. It should be in way such that I can use a FileSystemAccessor or ClassPathAccessor to load it again.
Is there some example how to do that?
Thanks,
Dieter
The way to do this is described at https://www.liquibase.org/bestpractices.html
The example given shows XML formatted changelogs, but the basic idea would be the same for YAML formatted changelogs.
Leave me a comment and I can generate a sample in YAML.
After some searching I found this on the liquibase repo:
https://github.com/liquibase/liquibase/blob/master/liquibase-core/src/test/resources/liquibase/parser/core/yaml/doubleNestedChangeLog.yaml
It is an example how you can separate your yaml files analog to the xml as shown by SteveDonies link.
The YAML mapping documentation for entities seems to be lacking. It doesn't explain what the different types, the different generator strategies, what mappedBy means, what types of cascade values are allowed, how to define a many-to-one relationship, and a whole lot more. Where can I find full documentation for this YAML file?
Unfortunately, the yaml format documentation for doctrine 2 is pretty limited at the moment.
Right now, the best way to figure out the yaml format is to look at the yaml driver implemetation.
Doctrine\ORM\Mapping\Driver\YamlDriver
Read through the the implementation of the loadMetadataForClass method. That shows you what properties the driver is expecting where.
You can also look at the annotations documentation to supplement your understanding. Many of the documented field names and expected values are the same as the yaml format. For example: once you figure out #column corresponds to the fields element of the yaml format, the rest of the annotations documentation for that element lines up with the yaml format.
You can have look at Doctrine\Orm\Mapping\ClassMetadataInfo class located at
path/to/doctrine/library/Orm/Mapping/ClassMetadataInfo.php
In this class you can find mostly what's possible. If you read the comments carefully it will give you a better idea.
The v1.2 manual is much more complete.