Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add YAML page/section to the docs #92

Open
grahamgower opened this issue Jun 30, 2021 · 4 comments
Open

add YAML page/section to the docs #92

grahamgower opened this issue Jun 30, 2021 · 4 comments
Labels
docs Improvements or additions to documentation

Comments

@grahamgower
Copy link
Member

It would be useful for readers to have a short explainer on YAML, exhibiting the major features relevant to writing Demes models. When I search for similar things on google, most of the top hits are rather terrible.

@grahamgower grahamgower added the docs Improvements or additions to documentation label Jun 30, 2021
@jeromekelleher
Copy link
Member

Good opportunity to steer people towards good practices too.

@grahamgower
Copy link
Member Author

I've been writing fairly adhoc YAML so far - do you have suggestions for best practices that we should adopt? Indentation level? Something else?

@jeromekelleher
Copy link
Member

The YAML you've produced all looks good to me - I guess we could find an auto formatter (Black for YAML?) and settle on that as our preferred way to do it? I don't think it's that simple though, as we want people to lay the models out in a readable way, and sometimes flow style is better than indentation, and vice versa.

Anyway, I don't have anything specific.

@grahamgower
Copy link
Member Author

https://www.yaml.info/learn/bestpractices.html
The site also has some other useful info, including a nice tutorial and an extensive discussion on when quoting of strings is required (TLDR: its stupidly complicated and unreasonably onerous to figure it out from the YAML spec). The tute is still not something I'd just want to link to though, because we'd need to also say "ignore the stuff about aliases, anchors and tags"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants