Improve yaml config docs

[stsewd]

The current types on the documentation are a mix of python and yaml. Related issue #2813

• According to the spec null is used http://yaml.org/spec/1.2/spec.html#id2803362
• Also there isn't a functional example of a yaml file. I wanted to add the yaml file from rtd, but there isn't one, yet, so this could be another PR :).

On this PR readthedocs/readthedocs-build#38 you can check that with this values the project works

[stsewd]

I think this would no work with the current implementation

https://github.com/rtfd/readthedocs-build/blob/daecec8b74af1f55b0ab4c1dd53d9cf6aee20126/readthedocs_build/config/config.py#L399-L409

This should be:

formats: null

[humitos]

Do we have a test that make this example fail?

[humitos]

Won't this change affect current users using it in this way?

[stsewd]

Now we have one :) readthedocs/readthedocs-build#43

Won't this change affect current users using it in this way?

The current description doesn't work for any user using it

[stsewd]

Mmm, now I see, this value is hardcoded as a string on the code. What should be done now?

[stsewd]

and now that I know the syntax for an empty list, would be better that this is represented as []

[agjohnson]

👍 on using the formats: [] syntax. This example will produce something we don't want:

In [1]: yaml.load("foo:\n  - null")
Out[1]: {'foo': [None]}

[stsewd]

Also there is a default type [] for an empty list, should be changed to be actually empty?

https://github.com/rtfd/readthedocs.org/blob/master/docs/yaml-config.rst#pythonextra_requirements

[humitos]

Also there is a default type [] for an empty list, should be changed to be actually empty?

I think the empty list is the correct default object for a field where a list is expected (instead of None).

[stsewd]

@humitos I was thinking something like this

python:
    extra_requirements:

But that is None, anyway... How to represent an empty list on yaml?

Edit: I found it, indeed is [] like python 😁

[agjohnson]

Great additions! 👍

We'll also want to make sure the empty list example for formats is correct and maybe even ensure this test case (we probably already do? good to check anyways)

[agjohnson]

👍 on using the formats: [] syntax. This example will produce something we don't want:

In [1]: yaml.load("foo:\n  - null")
Out[1]: {'foo': [None]}

[stsewd]

This is blocked due readthedocs/readthedocs-build#43

[agjohnson]

Unblocked!

[stsewd]

This is done

[humitos]

Good work!