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

moving docs to mkdocs #856

Merged
merged 24 commits into from Oct 7, 2019
Merged

moving docs to mkdocs #856

merged 24 commits into from Oct 7, 2019

Conversation

@samuelcolvin
Copy link
Owner

samuelcolvin commented Oct 2, 2019

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
samuelcolvin added 2 commits Oct 2, 2019
@codecov

This comment has been minimized.

Copy link

codecov bot commented Oct 2, 2019

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.

samuelcolvin added 8 commits Oct 2, 2019
@samuelcolvin samuelcolvin mentioned this pull request Oct 3, 2019
5 of 11 tasks complete
@dmontagu

This comment has been minimized.

Copy link
Collaborator

dmontagu commented Oct 3, 2019

This is gonna be really awesome!

samuelcolvin added 2 commits Oct 3, 2019
@samuelcolvin samuelcolvin marked this pull request as ready for review Oct 3, 2019
@samuelcolvin

This comment has been minimized.

Copy link
Owner Author

samuelcolvin commented Oct 3, 2019

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

This comment has been minimized.

Copy link
Collaborator

dmontagu commented Oct 4, 2019

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

docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/models.md Outdated Show resolved Hide resolved
docs/index.md Outdated Show resolved Hide resolved
docs/index.md Outdated Show resolved Hide resolved
docs/index.md Outdated Show resolved Hide resolved
docs/index.md Outdated Show resolved Hide resolved
docs/usage/dataclasses.md Outdated Show resolved Hide resolved
docs/usage/dataclasses.md Outdated Show resolved Hide resolved
@dmontagu

This comment has been minimized.

Copy link
Collaborator

dmontagu commented Oct 4, 2019

(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.)

docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/models.md Outdated Show resolved Hide resolved
docs/usage/types.md Outdated Show resolved Hide resolved
docs/usage/types.md Outdated Show resolved Hide resolved
```
_(This script is complete, it should run "as is")_

## Custom Data Types

This comment has been minimized.

Copy link
@dmontagu

dmontagu Oct 4, 2019

Collaborator

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.

This comment has been minimized.

Copy link
@samuelcolvin

samuelcolvin Oct 4, 2019

Author Owner

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.

docs/usage/model_config.md Show resolved Hide resolved
docs/usage/settings.md Outdated Show resolved Hide resolved
samuelcolvin and others added 2 commits Oct 4, 2019
incorporate @dmontagu's suggestions.

Co-Authored-By: dmontagu <35119617+dmontagu@users.noreply.github.com>
more missed suggestions.

Co-Authored-By: dmontagu <35119617+dmontagu@users.noreply.github.com>
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
changes/make_history.py Outdated Show resolved Hide resolved
docs/build/main.py Outdated Show resolved Hide resolved
docs/contributing.md Outdated Show resolved Hide resolved
docs/usage/model_config.md Show resolved Hide resolved
@samuelcolvin

This comment has been minimized.

Copy link
Owner Author

samuelcolvin commented Oct 4, 2019

@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.

more corrects.
This was referenced Oct 4, 2019
samuelcolvin added 5 commits Oct 7, 2019
samuelcolvin added 2 commits Oct 7, 2019
@samuelcolvin samuelcolvin merged commit 33b7d52 into master Oct 7, 2019
11 checks passed
11 checks passed
Header rules No header rules processed
Details
Pages changed 2 new files uploaded
Details
Redirect rules No redirect rules processed
Details
Mixed content No mixed content detected
Details
codecov/project 100% (+0%) compared to 8905e9a
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
deploy/netlify Deploy preview ready!
Details
samuelcolvin.pydantic Build #20191007.34 succeeded
Details
samuelcolvin.pydantic (Job Python36) Job Python36 succeeded
Details
samuelcolvin.pydantic (Job Python37) Job Python37 succeeded
Details
@haizaar

This comment has been minimized.

Copy link
Contributor

haizaar commented Oct 10, 2019

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

@dmontagu

This comment has been minimized.

Copy link
Collaborator

dmontagu commented Oct 10, 2019

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?

@samuelcolvin samuelcolvin deleted the mkdocs branch Oct 10, 2019
@haizaar

This comment has been minimized.

Copy link
Contributor

haizaar commented Oct 10, 2019

@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

This comment has been minimized.

Copy link
Owner Author

samuelcolvin commented Oct 10, 2019

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

This comment has been minimized.

Copy link
Contributor

haizaar commented Oct 10, 2019

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.