moving docs to mkdocs

[samuelcolvin]

Change Summary

Move all docs to mkdocs

fixes #578

Still to do:

• add an intro to models.md
• add an intro to types.md
• fix "TODO: warning about field order"
• remove "Required Fields and mypy" section in mypy
• fix benchmarks (should be regenerated for v1 anyway), needs to output an md table not csv

[codecov]

Codecov Report

Merging #856 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff           @@
##           master   #856    +/-   ##
======================================
  Coverage     100%   100%            
======================================
  Files          17     16     -1     
  Lines        3132   2716   -416     
  Branches      610    518    -92     
======================================
- Hits         3132   2716   -416

Impacted Files	Coverage Δ
pydantic/env_settings.py	100% <ø> (ø)	⬆️
pydantic/version.py	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8905e9a...8d33898. Read the comment docs.

[dmontagu]

This is gonna be really awesome!

[samuelcolvin]

this is ready to review, feedback very welcome.

I see need to fix benchmarks before this can be merged, and there's #862 to do later, but unless there are any major problems this should be merged soon since it's already better than what went before.

[dmontagu]

I'm looking at it now -- this is awesome!!

[dmontagu]

(Feel free to just mark resolved any suggestions that you disagree with. Also let me know if you don't want me to point out the typos like this.)

[dmontagu]

For what it's worth, I personally think this section, short as it is, merits its own top level page, separate from all the other types.

(It may also be worth expanding that page..)

This is such a useful feature and I think it doesn't get the attention it deserves -- it's a shame for it to be buried way at the bottom of the long list of types pydantic provides.

[samuelcolvin]

okay, personally I think it's right here but we should link to it more and expand it to contain more details and a better example. Certainly the current example is awful.

[samuelcolvin]

@dmontagu thank you very much for your review. I know this stuff isn't much fun, but I'm very dyslexic and corrections like this make the docs a lots easier to use and looks a lot more professional.

[haizaar]

Guys, can you please elaborate why did you decided to switch from rst/sphinx to mkdocs? Any particular advantages in favor the latter?

[dmontagu]

I think the new (hierarchical) organization is a big improvement; it's not just a massive wall of text. I'm not sure that by itself necessitated the move to mkdocs though.

---

I can't speak for what motivated @samuelcolvin to move to mkdocs, but I personally think it now looks much nicer than the old docs page, and hopefully feels a little more modern for prospective new users.

And at least one person has commented positively (from the fastapi gitter):

btw, just realized pydantic reached 1.0 and had a very nice facelift for their doc!

---

@haizaar Do you have any issues with new docs format?

[haizaar]

@dmontagu not at all. They are aesthetically pleasing. Though there are nice sphinx templates our there as well. And of course you can create hierarchical docs with sphinx as well. I wonder if material design was the main thing. Or may be Samuel just wanted get some experience with mkdocs :)

Again, I have absolutely no problems/issues with the docs. Just being curious.

[samuelcolvin]

1. Markdown vs. reStructuredText

Many developers find markdown much more intuitive to use than rst. I know rst has many powerful features but it's also extraordinarily convoluted to do simple things e.g. links are

`name <https://www.example.com/>`_

I find this amazingly complex. Even after having written thousands of lines of it, I still have to search for an example of things that are trivial in md.

I hope people will be more willing to help with the docs now they're written in markdown.

2. mkdocs vs. sphinx

mkdocs definitely isn't perfect, there are some design decisions I strongly disagree with. However overall it's a lot more use friendly than sphinx: mkdocs serve alone makes a significant difference to the feedback loop when writing docs. I think there's also a richer ecosystem of themes available for mkdocs.

---

I wonder if material design was the main thing.

Not really, though I do think it's nice.

Or may be Samuel just wanted get some experience with mkdocs :)

If only, we used a mkdocs site for the help site of the company I run for many years. mkdocs is an old frenemy.

---

In short:

1. I enjoy writing the docs. now more than before.
2. I enjoy reading the docs. now more than before.

[haizaar]

Thanks for sharing! Appreciate that! I saw mkdocs becoming quite popular in Python world and was very curious to hear experience from someone who designed to switch. Thanks again!