8000 moving docs to mkdocs (#856) · ag-python/pydantic@33b7d52 · GitHub
[go: up one dir, main page]
Skip to content

Commit 33b7d52

Browse files
samuelcolvinsamuelcolvin
authored
moving docs to mkdocs (pydantic#856)
* moving docs to mkdocs * transfering readme to md and more * fixing build * splitting usage.md * improving schema.md and index.md * fix make_history.rst * models intro * working on data conversation and required fields * more fixes to models.md * list all standard types supported * list of pydantic types * tweaks * update links in code * Apply suggestions from code review incorporate @dmontagu's suggestions. Co-Authored-By: dmontagu <35119617+dmontagu@users.noreply.github.com> * Apply suggestions from code review more missed suggestions. Co-Authored-By: dmontagu <35119617+dmontagu@users.noreply.github.com> * Apply suggestions from code review more corrects. * cleanup * Field order warning * fix and regenerate benchmarks * format examples better, cleanup * improve schema mapping table * correct highlighting file types in schema.md * add redirects in javascript * add logo
1 parent 8905e9a commit 33b7d52

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+2992
-2772
lines changed

‎.gitignore

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,13 @@ dist/
1010
.mypy_cache/
1111
test.py
1212
.coverage
13-
htmlcov/
14-
benchmarks/*.json
15-
docs/_build/
16-
docs/.TMP_HISTORY.rst
17-
docs/.tmp_schema_mappings.rst
13+
/htmlcov/
14+
/benchmarks/*.json
15+
/docs/.changelog.md
16+
/docs/.version.md
17+
/docs/.tmp_schema_mappings.html
18+
/site/
19+
/site.zip
1820
.pytest_cache/
1921
.vscode/
2022
_build/

‎.travis.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ script:
2020
- python3 ./changes/make_history.py
2121
- make lint
2222
- make mypy
23+
- make check-dist
2324

2425
env:
2526
global:

‎HISTORY.md

Lines changed: 442 additions & 0 deletions
Large diffs are not rendered by default.

‎HISTORY.rst

Lines changed: 0 additions & 447 deletions
This file was deleted.

‎MANIFEST.in

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
include LICENSE
2-
include README.rst
3-
include HISTORY.rst
2+
include README.md
3+
include HISTORY.md

‎Makefile

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,16 @@ format:
2323

2424
.PHONY: lint
2525
lint:
26-
python setup.py check -rms
2726
flake8 pydantic/ tests/
2827
$(isort) --check-only
2928
$(black) --check
3029

30+
.PHONY: check-dist
31+
check-dist:
32+
python setup.py check -ms
33+
SKIP_CYTHON=1 python setup.py sdist
34+
twine check dist/*
35+
3136
.PHONY: mypy
3237
mypy:
3338
mypy pydantic
@@ -80,14 +85,25 @@ clean:
8085
rm -rf dist
8186
rm -f pydantic/*.c pydantic/*.so
8287
python setup.py clean
83-
make -C docs clean
88+
rm -rf site
89+
rm -rf docs/_build
8490

8591
.PHONY: docs
8692
docs:
87-
make -C docs html
93+
./docs/build/main.py
94+
mkdocs build
95+
@# to work with the old sphinx build and deploy:
96+
@rm -rf docs/_build/
97+
@mkdir docs/_build/
98+
@cp -r site docs/_build/html
99+
100+
.PHONY: docs-serve
101+
docs-serve:
102+
./docs/build/main.py
103+
mkdocs serve
88104

89105
.PHONY: publish
90106
publish: docs
91-
cd docs/_build/ && cp -r html site && zip -r site.zip site
107+
zip -r site.zip site
92108
@curl -H "Content-Type: application/zip" -H "Authorization: Bearer ${NETLIFY}" \
93-
--data-binary "@docs/_build/site.zip" https://api.netlify.com/api/v1/sites/pydantic-docs.netlify.com/deploys
109+
--data-binary "@site.zip" https://api.netlify.com/api/v1/sites/pydantic-docs.netlify.com/deploys

‎README.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# pydantic
2+
3+
[![BuildStatus](https://travis-ci.org/samuelcolvin/pydantic.svg?branch=master)](https://travis-ci.org/samuelcolvin/pydantic)
4+
[![Coverage](https://codecov.io/gh/samuelcolvin/pydantic/branch/master/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/pydantic)
5+
[![pypi](https://img.shields.io/pypi/v/pydantic.svg)](https://pypi.python.org/pypi/pydantic)
6+
[![CondaForge](https://img.shields.io/conda/v/conda-forge/pydantic.svg)](https://anaconda.org/conda-forge/pydantic)
7+
[![downloads](https://img.shields.io/pypi/dm/pydantic.svg)](https://pypistats.org/packages/pydantic)
8+
[![versions](https://img.shields.io/pypi/pyversions/pydantic.svg)](https://github.com/samuelcolvin/pydantic)
9+
[![license](https://img.shields.io/github/license/samuelcolvin/pydantic.svg)](https://github.com/samuelcolvin/pydantic/blob/master/LICENSE)
10+
11+
Data validation and settings management using Python type hinting.
12+
13+
Fast and extensible, *pydantic* plays nicely with your linters/IDE/brain.
14+
Define how data should be in pure, canonical Python 3.6+; validate it with *pydantic*.
15+
16+
## Help
17+
18+
See [documentation](https://pydantic-docs.helpmanual.io/) for more details.
19+
20+
## Installation
21+
22+
Install using `pip install -U pydantic` or `conda install pydantic -c conda-forge`.
23+
For more installation options to make *pydantic* even faster,
24+
see the [Install](https://pydantic-docs.helpmanual.io/install/) section in the documentation.
25+
26+
## A Simple Example
27+
28+
```py
29+
from datetime import datetime
30+
from typing import List
31+
from pydantic import BaseModel
32+
33+
class User(BaseModel):
34+
id: int
35+
name = 'John Doe'
36+
signup_ts: datetime = None
37+
friends: List[int] = []
38+
39+
external_data = {'id': '123', 'signup_ts': '2017 2851 -06-01 12:22', 'friends': [1, '2', b'3']}
40+
user = User(**external_data)
41+
print(user)
42+
#> User id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
43+
print(user.id)
44+
#> 123
45+
```
46+
47+
## Contributing
48+
49+
For guidance on setting up a development environment and how to make a
50+
contribution to *pydantic*, see
51+
[Contributing to Pydantic](https://pydantic-docs.helpmanual.io/contributing/).

‎README.rst

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎benchmarks/run.py

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import csv
21
import json
32
from operator import itemgetter
43

@@ -7,7 +6,6 @@
76
import string
87
import sys
98
from datetime import datetime
10-
from io import StringIO
119

1210
from devtools import debug
1311
from functools import partial
@@ -177,26 +175,36 @@ def main():
177175
sd = stdev(times) / model_count * 1e6
178176
results.append(f'{p:>40} best={min(times) / model_count * 1e6:0.3f}μs/iter '
179177
f'avg={avg:0.3f}μs/iter stdev={sd:0.3f}μs/iter')
180-
csv_results.append([p, avg, sd])
178+
csv_results.append([p, test_class.version, avg])
181179
print()
182180

183181
for r in results:
184182
print(r)
185183

186184
if 'SAVE' in os.environ:
187-
csv_file = StringIO()
188-
csv_writer = csv.writer(csv_file)
189-
first_avg = None
190-
for p, avg, sd in sorted(csv_results, key=itemgetter(1)):
191-
if first_avg:
192-
relative = f'{avg / first_avg:0.1f}x slower'
193-
else:
194-
relative = ''
195-
first_avg = avg
196-
csv_writer.writerow([p, relative, f'{avg:0.1f}μs', f'{sd:0.3f}μs'])
197-
p = Path(THIS_DIR / '../docs/benchmarks.csv')
198-
print(f'saving results to {p}')
199-
p.write_text(csv_file.getvalue())
185+
save_md(csv_results)
186+
187+
188+
def save_md(data):
189+
headings = 'Package', 'Version', 'Relative Performance', 'Mean validation time'
190+
rows = [headings, ['---' for _ in headings]]
191+
192+
first_avg = None
193+
for package, version, avg in sorted(data, key=itemgetter(2)):
194+
if first_avg:
195+
relative = f'{avg / first_avg:0.1f}x slower'
196+
else:
197+
relative = ''
198+
first_avg = avg
199+
rows.append([package, f'`{version}`', relative, f'{avg:0.1f}μs'])
200+
201+
table = '\n'.join(' | '.join(row) for row in rows)
202+
text = f"""\
203+
[//]: <> (Generated with benchmarks/run.py, DO NOT EDIT THIS FILE DIRECTLY, instead run `SAVE=1 python ./run.py`.)
204+
205+
{table}
206+
"""
207+
(Path(__file__).parent / '..' / 'docs' / '.benchmarks_table.md').write_text(text)
200208

201209

202210
def diff():

‎benchmarks/test_drf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@
66
)
77
django.setup()
88

9-
from rest_framework import serializers
9+
from rest_framework import __version__, serializers
1010

1111

1212
class TestDRF:
1313
package = 'django-restful-framework'
14+
version = __version__
1415

1516
def __init__(self, allow_extra):
1617
class Model(serializers.Serializer):

‎benchmarks/test_marshmallow.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
from marshmallow import Schema, fields, validate
1+
from marshmallow import Schema, __version__, fields, validate
22

33

44
class TestMarshmallow:
55
package = 'marshmallow'
6+
version = __version__
67

78
def __init__(self, allow_extra):
89
class LocationSchema(Schema):
@@ -21,7 +22,7 @@ class Model(Schema):
2122
id = fields.Integer(required=True)
2223
client_name = fields.Str(validate=validate.Length(max=255), required=True)
2324
sort_index = fields.Float(required=True)
24-
#client_email = fields.Email()
25+
# client_email = fields.Email()
2526
client_phone = fields.Str(validate=validate.Length(max=255), allow_none=True)
2627

2728
location = LocationSchema()

‎benchmarks/test_pydantic.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
from datetime import datetime
22
from typing import List
33

4-
from pydantic import BaseModel, Extra, PositiveInt, ValidationError, constr
4+
from pydantic import VERSION, BaseModel, Extra, PositiveInt, ValidationError, constr
55

66

77
class TestPydantic:
88
package = 'pydantic'
9+
version = str(VERSION)
910

1011
def __init__(self, allow_extra):
11-
1212
class Model(BaseModel):
1313
id: int
1414
client_name: constr(max_length=255)
@@ -19,6 +19,7 @@ class Model(BaseModel):
1919
class Location(BaseModel):
2020
latitude: float = None
2121
longitude: float = None
22+
2223
location: Location = None
2324

2425
contractor: PositiveInt = None
@@ -33,6 +34,7 @@ class Skill(BaseModel):
3334
qual_level: str
3435
qual_level_id: int
3536
qual_level_ranking: float = 0
37+
3638
skills: List[Skill] = []
3739

3840
class Config:

‎benchmarks/test_toasted_marshmallow.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
import toastedmarshmallow
2+
23
from test_marshmallow import TestMarshmallow
34

45

56
class TestToastedMarshmallow(TestMarshmallow):
67
package = 'toasted-marshmallow'
8+
version = toastedmarshmallow.__version__
79

810
def __init__(self, allow_extra):
911
super().__init__(allow_extra)

‎benchmarks/test_trafaret.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
class TestTrafaret:
66
package = 'trafaret'
7+
version = '.'.join(map(str, t.__VERSION__))
78

89
def __init__(self, allow_extra):
910
self.schema = t.Dict({

‎changes/856-samuelcolvin.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Transfer the documentation build from sphinx to mkdocs, write much of the do documentation

‎changes/README.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
This directory contains files describing changes to pydantic since the last release.
44

55
If you're creating a pull request, please add a new file to this directory called
6-
`<pull request or issue id>-<github username>.rst`. It should be formatted as a single paragraph of
7-
[reStructuredText](http://docutils.sourceforge.net/rst.html).
6+
`<pull request or issue id>-<github username>.md`. It should be formatted as a single paragraph of markdown
87

9-
The contents of this file will be used to update `HISTORY.rst` before the next release.
8+
The contents of this file will be used to update `HISTORY.md` before the next release.

0 commit comments

Comments
 (0)
0