docs linting and improving first example

.travis.yml

@@ -13,6 +13,12 @@ matrix:
   allow_failures:
   - python: 'nightly'
 
+addons:
+  apt:
+    packages:
+    - libenchant-dev
+    - c2hs
+
 install:
 - make install
 - pip freeze
@@ -21,6 +27,7 @@ script:
 - make lint
 - make test
 - make benchmark
+- make docs-lint
 - make docs
 - ./tests/check_tag.py
 

Makefile

@@ -1,9 +1,8 @@
 .PHONY: install
 install:
 	pip install -U setuptools pip
+	pip install -r requirements.txt
 	pip install -U .
-	pip install -r tests/requirements.txt
-	pip install -r benchmarks/requirements.txt
 
 .PHONY: isort
 isort:
@@ -48,12 +47,14 @@ clean:
 
 .PHONY: docs
 docs:
-	make -C docs clean
 	make -C docs html
-	@echo "open file://`pwd`/docs/_build/html/index.html"
+
+.PHONY: docs-lint
+docs-lint:
+	make -C docs lint
 
 .PHONY: deploy-docs
-deploy-docs: docs
+deploy-docs: docs-lint docs
 	cd docs/_build/ && cp -r html site && zip -r site.zip site
 	@curl -H "Content-Type: application/zip" -H "Authorization: Bearer ${NETLIFY}" \
-			--data-binary "@docs/_build/site.zip" https://api.netlify.com/api/v1/sites/pydantic-docs.netlify.com/deploys
+	      --data-binary "@docs/_build/site.zip" https://api.netlify.com/api/v1/sites/pydantic-docs.netlify.com/deploys

docs/Makefile

@@ -13,11 +13,11 @@ clean:
 	rm -rf $(BUILDDIR)
 
 .PHONY: html
-html:
+html: clean
 	mkdir -p $(STATICDIR)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. open file://`pwd`/_build/html/index.html"
 
 .PHONY: linkcheck
 linkcheck:
@@ -27,9 +27,12 @@ linkcheck:
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-.PHONY: doctest
-doctest:
+.PHONY: spelling
+spelling:
 	mkdir -p $(STATICDIR)
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
+
+.PHONY: lint
+lint: linkcheck spelling
+	@echo
+	@echo "linting complete"

docs/conf.py

@@ -37,7 +37,10 @@ extensions = [
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinxcontrib.spelling',
 ]
+spelling_lang = 'en_GB'
+spelling_word_list_filename = 'spelling_wordlist.txt'
 
 autoclass_content = 'both'
 autodoc_member_order = 'bysource'

docs/example1.py

@@ -1,14 +1,16 @@
 from datetime import datetime
+from typing import List
 from pydantic import BaseModel
 
 class UserModel(BaseModel):
     id: int = ...
     name = 'John Doe'
     signup_ts: datetime = None
+    friends: List[int] = []
 
-external_data = {'id': '123', 'signup_ts': '2017-06-01 12:22'}
+external_data = {'id': '123', 'signup_ts': '2017-06-01 12:22', 'friends': [1, '2', b'3']}
 user = UserModel(**external_data)
 print(user)
-# > UserModel id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22)
+# > UserModel id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
 print(user.id)
 # > 123

docs/index.rst

@@ -24,11 +24,12 @@ Simple example:
 
 What's going on here:
 
-* ``id`` is of type int, the elipsis tells pydantic this field is required. Strings, bytes or floats will be
+* ``id`` is of type int, the ellipsis tells pydantic this field is required. Strings, bytes or floats will be
   converted to ints if possible, otherwise an exception would be raised.
-* ``name`` pydantic infers is a string from the default, it is not required as it has a default
+* ``name`` pydantic infers as a string from the default, it is not required as it has a default
 * ``signup_ts`` is a datetime field which is not required (``None`` if it's not supplied), pydantic will process
-  either a unix timestamp int (eg. ``1496498400``) or a string representing the date & time.
+  either a unix timestamp int (e.g. ``1496498400``) or a string representing the date & time.
+* ``friends`` uses python's typing system, it is required to be a list of ints,
 
 If validation fails pydantic with raise an error with a breakdown of what was wrong:
 
@@ -44,7 +45,7 @@ So *pydantic* uses some cool new language feature, but why should I actually go
     `type hinting docs <https://docs.python.org/3/library/typing.html>`_) you know how to use pydantic.
 
 **plays nicely with your IDE/linter/brain**
-    because pydantic data structures are just instances of classes you define; autocompleting, linting,
+    because pydantic data structures are just instances of classes you define; auto-completion, linting,
     `mypy <http://mypy-lang.org/>`_ your intuition should all work properly with your validated data.
 
 **dual use**
@@ -134,8 +135,8 @@ Here default for config parameter are shown together with their meaning.
 Settings
 ........
 
-One of pydantics most useful applications is to define default settings, allow them to be overridden by
-environment variables or keyword arguments (eg. in unit tests).
+One of pydantic's most useful applications is to define default settings, allow them to be overridden by
+environment variables or keyword arguments (e.g. in unit tests).
 
 This usage example comes last as it uses numerous concepts described above.
 

docs/requirements.txt

@@ -0,0 +1,5 @@
+docutils==0.13.1
+Pygments==2.2.0
+Sphinx==1.6.2
+sphinxcontrib-spelling==2.3.0
+sphinxcontrib-websupport==1.0.1

docs/spelling_wordlist.txt

@@ -0,0 +1,10 @@
+cerberus
+Config
+config
+ints
+jsonmodels
+pydantic
+schemas
+unix
+untrusted
+ve

requirements.txt

@@ -0,0 +1,3 @@
+-r benchmarks/requirements.txt
+-r docs/requirements.txt
+-r tests/requirements.txt

tests/requirements.txt

@@ -1,5 +1,4 @@
 coverage==4.4.1
-docutils==0.13.1
 flake8==3.3.0
 pycodestyle==2.3.1
 pyflakes==1.5.0
@@ -7,5 +6,3 @@ pytest==3.1.1
 pytest-cov==2.5.1
 pytest-isort==0.1.0
 pytest-sugar==0.8.0
-Pygments==2.2.0
-Sphinx==1.6.2