API Documentation Woefully Incomplete

[macdjord]

The documentation of the PyYAML API at https://pyyaml.org/wiki/PyYAMLDocumentation (besides being out of date) is woefully incomplete. Most of the functions and classes listed there have no description at all, and none of them have explanations of their arguments optional arguments.

For instance, four different functions take allow_unicode as an argument, but nowhere on that page is there an explanation of what it does or what the default is. Similarly, the width parameter is undocumented in the API listing; the tutorial section on 'Dumping YAML' does explain that "you may set the preferred intendation[sic] and width", but no details of what a given width setting will do (what types of content will or will not be broken up? Is the output guaranteed to stay within the limit, or is it possible for some inputs to force the limit to be exceeded?) or what the default behaviour is.

Also, that page has no table of contents, nor any indication that the API reference even exists (hidden as it is below the YAML syntax primer).

Ideally, that entire page should be decommissioned and replaced with a modern, well-formatted readthedocs.org page.

[metov]

I'd like to help out with this, but I am not familiar enough with the project to write a full manual from scratch. I do agree that the current documentation could use an overhaul - while it contains a good amount of information, the way it's organized makes it difficult to learn the library or use it as a reference.

I think the solution to this issue can be broken into several parts:

1. Setting up a docs/ dir and integrating it with readthedocs.org
2. Migrating existing docs from https://pyyaml.org/wiki/PyYAMLDocumentation to readthedocs
3. Reorganizing docs into sections
4. Expanding on any gaps in the documentation

I probably can't help with 4 because I don't know the codebase well enough. However I'd be happy to do 1-3 if the maintainers are supportive.

[jayeye]

The fundamental problem here is that documentation should not be an afterthought. Why bother releasing code if people can't use it without tearing their hair out?

[tgherzog]

A simple description of the parameters to dump() and load() with corresponding value lists would be immensely helpful.