Pydantic: Improvements to Docs

[samuelcolvin]

Docs are being rebuilt with mkdocs in #856, that PR is already very large.

More things to do later:

• [x] check all examples:
  
  
  
  1. are used
  
  
  2. pass or fail as expected
  
  
• [x] add a section on migrating from v0.x to v1
• [x] check examples have maximum line length of 79 or something
• [ ] rename examples to make sense
• [x] custom icon and favicon
• [ ] check all links work
• [x] setup redirects from old links to the new site
• [ ] extend the "Constrained Types" to explain about mypy and creating your own types
• [ ] give more details on the standard library and custom types listed in types.md
• [ ] https://github.com/samuelcolvin/pydantic/pull/856#discussion_r331418795 better example of custom types, aka #789
• [ ] add more info to the mypy section, e.g.: how dataclasses work, use of Field

[dmontagu]

check examples have maximum line length of 79 or something

Might be easiest to just call isort/black/flake8-quotes on the examples with the desired settings.

Since the docs are no longer going to be one long page to scroll through, I personally think it's okay if the example code becomes slightly longer due to the standard formatting.

[samuelcolvin]

maybe, but I think it'll be annoying in docs examples where expressiveness should take precedence over correctness.

[dmontagu]

Does isort/black cause issues with expressiveness?

(I just said flake8-quotes to ensure double quotes get checked; not for all of the rest of flake8. That could obviously be dropped if you are willing to just keep an eye out for violations manually.)

(I'm definitely not suggesting we add flake8/mypy checking for the examples.)

[samuelcolvin]

makes more sense. The only problem I can see is that we use

print(whatever)
#> ['this', 'is', 'whatever']

syntax a lot in examples and black will change it to # > which I find ugly, but maybe we can live with that.

All that said, it would take a 10 line python script to check line lengths, and we'll need some custom code to run all code examples and check they pass or fail as expected anyway.

[dmontagu]

Yeah, I think it would also force more space between top level comments which we might not want. So I think it makes more sense to go with the approach you are describing

[koxudaxi]

I created to assert an example script.
This script is simple and, don't cover edge cases, but the script may help to check pydantic examples.

https://gist.github.com/koxudaxi/e44b5a7bf21c00e0131a9e805ba3bb32
I try to run the script to docs/example/example1.py in the master branch.

python3 ~/assert_example.py --input docs/examples/example1.py                           
Diff:
- User id=123 signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3] name='John Doe'
?                                                                              ----------------

+ User id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
?            ++++++++++++++++


Actual:
User id=123 signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3] name='John Doe'

Failed: docs/examples/example1.py

The script compares called argument of print() and the next line comments.

If you need help to check the example file then, I will do it.

[samuelcolvin]

forgot to say:

@koxudaxi, I took your example and modified it a lot, now all print statement output is generated when docs are being built and inserted into the scripts, so they can't go out of date. Thanks.

[koxudaxi]

@samuelcolvin
I am happy to be of help :)

[PrettyWood]

@samuelcolvin I'm checking out open issues to see if some are already solved. Should this one be closed?