Refector docs (#5270)

* moving examples into docs

* examples passing!

* fix for older python

* fix a few more tests

* fix docs dependencies

* xfail some discriminated union tests

* more skipping

* make tests run

* switch to mkdocs-simple-hooks for build

* using pyupgrade on examples

* fix devtools

* no mypy on plugins

* run isort on examples

* fix devtools newline

* uprev deps

* fix test_docs, add docs --verbose build

* fix more build errors

* fixing ci (i hope)

* another test-requires

.github/workflows/ci.yml

@@ -65,28 +65,15 @@ jobs:
     steps:
     - uses: actions/checkout@v3
 
-    - name: set up python
-      uses: actions/setup-python@v4
+    - uses: actions/setup-python@v4
       with:
         python-version: '3.10'
 
-    - uses: actions/cache@v3
-      id: cache
-      with:
-        path: ${{ env.pythonLocation }}
-        key: >
-          docs-build-v2
-          ${{ runner.os }}
-          ${{ env.pythonLocation }}
-          ${{ hashFiles('pyproject.toml') }}
-          ${{ hashFiles('requirements/*') }}
-
     - name: install
-      if: steps.cache.outputs.cache-hit != 'true'
-      run: pip install -r requirements/all.txt .
+      run: pip install -r requirements/docs.txt
 
-    - name: build site
-      run: make docs
+    - run: python -c 'import docs.plugins.main'
+    - run: mkdocs build --verbose
 
     - name: Store docs site
       uses: actions/upload-artifact@v3
@@ -127,7 +114,7 @@ jobs:
         run: pip install .
 
       - name: test
-        run: pytest --ignore=tests/mypy/ --memray
+        run: pytest --ignore=tests/mypy/ --ignore=tests/test_docs.py --memray
 
   test:
     name: test ${{ matrix.os }} / ${{ matrix.python-version }}

.gitignore

@@ -17,12 +17,7 @@ test.py
 .hypothesis
 /htmlcov/
 /benchmarks/*.json
-/docs/.changelog.md
-/docs/.version.md
-/docs/.tmp_schema_mappings.html
-/docs/.tmp_examples/
-/docs/.tmp-projections/
-/docs/usage/.tmp-projections/
+/docs/changelog.md
 /site/
 /site.zip
 .pytest_cache/

.mypy-configs/fast.toml

@@ -30,7 +30,5 @@ module = [
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-module = [
-    'pydantic_core.*',
-]
-follow_imports = "skip"
+module = ['pydantic_core.*', 'devtools.*']
+follow_imports = 'skip'

.mypy-configs/full.toml

@@ -28,3 +28,7 @@ module = [
     'devtools.*',
 ]
 ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ['devtools.*']
+follow_imports = 'skip'

Makefile

@@ -1,5 +1,5 @@
 .DEFAULT_GOAL := all
-sources = pydantic tests docs/build
+sources = pydantic tests docs/plugins
 
 .PHONY: install
 install:
@@ -31,11 +31,11 @@ lint:
 
 .PHONY: typecheck
 typecheck:
-	mypy pydantic docs/build --disable-recursive-aliases --config-file .mypy-configs/full.toml
+	mypy pydantic --disable-recursive-aliases --config-file .mypy-configs/full.toml
 
 .PHONY: typecheck-fast
 typecheck-fast:
-	mypy pydantic docs/build --disable-recursive-aliases --config-file .mypy-configs/fast.toml
+	mypy pydantic --disable-recursive-aliases --config-file .mypy-configs/fast.toml
 
 .PHONY: test-mypy
 test-mypy:
@@ -96,11 +96,4 @@ clean:
 
 .PHONY: docs
 docs:
-	ruff docs/examples/
-	python docs/build/main.py
 	mkdocs build
-
-.PHONY: docs-serve
-docs-serve:
-	python docs/build/main.py
-	mkdocs serve

docs/blog/pydantic-v2.md

@@ -241,9 +241,10 @@ my misgivings about marking a field as `Optional[int]` but requiring a value to
 
 In pydantic V2, pydantic will move to match dataclasses, thus:
 
-```py title="Required vs. Nullable"
+```py title="Required vs. Nullable" test="skip" lint="skip" upgrade="skip"
 from pydantic import BaseModel
 
+
 class Foo(BaseModel):
     f1: str  # required, cannot be None
     f2: str | None  # required, can be None - same as Optional[str] / Union[str, None]
@@ -268,10 +269,11 @@ Fields which use a function for validation can be any of the following types:
 
 An example how a wrap validator might look:
 
-```py title="Wrap mode validator function"
+```py title="Wrap mode validator function" test="skip" lint="skip" upgrade="skip"
 from datetime import datetime
 from pydantic import BaseModel, ValidationError, validator
 
+
 class MyModel(BaseModel):
     timestamp: datetime
 
@@ -297,7 +299,7 @@ pydantic-core can support alias "paths" as well as simple string aliases to flat
 
 Best demonstrated with an example:
 
-```py title="Alias paths"
+```py title="Alias paths" test="skip" lint="skip" upgrade="skip"
 from pydantic import BaseModel, Field
 
 
@@ -360,9 +362,10 @@ See [pydantic#1549](https://github.com/pydantic/pydantic/issues/1549) for motiva
 
 Here's an example of `context` might be used:
 
-```py title="Context during Validation"
+```py title="Context during Validation" test="skip" lint="skip" upgrade="skip"
 from pydantic import BaseModel, EmailStr, validator
 
+
 class User(BaseModel):
     email: EmailStr
     home_country: str
@@ -373,6 +376,7 @@ class User(BaseModel):
             raise ValueError('invalid country choice')
         return v
 
+
 async def add_user(post_data: bytes):
     countries = set(await db_connection.fetch_all('select code from country'))
     user = User.model_validate_json(post_data, context={'countries': countries})
@@ -405,7 +409,7 @@ All methods on models will start with `model_`, fields' names will not be allowe
 
 This will mean `BaseModel` will have roughly the following signature.
 
-```{.py .annotate title="New BaseModel methods"}
+```{.py .annotate title="New BaseModel methods" test="skip" lint="skip" upgrade="skip"}
 class BaseModel:
     model_fields: List[FieldInfo]
     """previously `__fields__`, although the format will change a lot"""
@@ -537,7 +541,7 @@ docs.
 
 Thus, errors might look like:
 
-```py title="Line Errors Example"
+```py title="Line Errors Example" test="skip" lint="skip" upgrade="skip"
 [
     {
         'kind': 'greater_than_equal',
@@ -609,9 +613,10 @@ an error or returning the validation result.
 
 To be clear, this isn't a real `isinstance` call, rather it is equivalent to
 
-```py title="is_instance"
+```py title="is_instance" test="skip" lint="skip" upgrade="skip"
 class BaseModel:
     ...
+
     @classmethod
     def model_is_instance(cls, data: Any) -> bool:
         try:
@@ -648,9 +653,10 @@ item can be a string, if so a function of that name will be taken from the class
 
 Here's an example of how a custom field type could be defined:
 
-```py title="New custom field types"
+```py title="New custom field types" test="skip" lint="skip" upgrade="skip"
 from pydantic import ValidationSchema
 
+
 class Foobar:
     def __init__(self, value: str):
         self.value = value
@@ -659,7 +665,7 @@ class Foobar:
         'type': 'function',
         'mode': 'after',
         'function': 'validate',
-        'schema': {'type': 'str'}
+        'schema': {'type': 'str'},
     }
 
     @classmethod
@@ -790,7 +796,7 @@ We will endeavour to read and respond to everyone.
 At the center of pydantic v2 will be a `PydanticValidator` class which looks roughly like this
 (note: this is just pseudo-code, it's not even valid python and is only supposed to be used to demonstrate the idea):
 
-```py title="PydanticValidator"
+```py title="PydanticValidator" test="skip" lint="skip" upgrade="skip"
 # type identifying data which has been validated,
 # as per pydantic-core, this can include "fields_set" data
 ValidData = ...