Markdown documentation

Author: p1c2u

.github/workflows/build-docs.yml

@@ -42,11 +42,11 @@ jobs:
 
       - name: Build documentation
         run: |
-          poetry run python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html -n -W
+          poetry run python -m mkdocs build --clean --site-dir ./_build/html --config-file mkdocs.yml
 
       - uses: actions/upload-artifact@v4
         name: Upload docs as artifact
         with:
           name: docs-html
-          path: './docs/_build/html'
+          path: './_build/html'
           if-no-files-found: error

.readthedocs.yaml

@@ -2,9 +2,9 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: mkdocs.yml
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all

docs/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
     "sphinx_immaterial",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -103,3 +104,8 @@
     # If False, expand all TOC entries
     "globaltoc_collapse": False,
 }
+
+myst_enable_extensions = [
+    "deflist",
+    "colon_fence",
+]

docs/contributing.md

@@ -0,0 +1,73 @@
+---
+hide:
+  - navigation
+---
+
+# Contributing
+
+Firstly, thank you all for taking the time to contribute.
+
+The following section describes how you can contribute to the openapi-core project on GitHub.
+
+## Reporting bugs
+
+### Before you report
+
+- Check whether your issue does not already exist in the [Issue tracker](https://github.com/python-openapi/openapi-core/issues).
+- Make sure it is not a support request or question better suited for [Discussion board](https://github.com/python-openapi/openapi-core/discussions).
+
+### How to submit a report
+
+- Include clear title.
+- Describe your runtime environment with exact versions you use.
+- Describe the exact steps which reproduce the problem, including minimal code snippets.
+- Describe the behavior you observed after following the steps, pasting console outputs.
+- Describe expected behavior to see and why, including links to documentations.
+
+## Code contribution
+
+### Prerequisites
+
+Install [Poetry](https://python-poetry.org) by following the [official installation instructions](https://python-poetry.org/docs/#installation). Optionally (but recommended), configure Poetry to create a virtual environment in a folder named `.venv` within the root directory of the project:
+
+```console
+poetry config virtualenvs.in-project true
+```
+
+### Setup
+
+To create a development environment and install the runtime and development dependencies, run:
+
+```console
+poetry install
+```
+
+Then enter the virtual environment created by Poetry:
+
+```console
+poetry shell
+```
+
+### Static checks
+
+The project uses static checks using fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit.
+
+To turn on pre-commit checks for commit operations in git, enter:
+
+```console
+pre-commit install
+```
+
+To run all checks on your staged files, enter:
+
+```console
+pre-commit run
+```
+
+To run all checks on all files, enter:
+
+```console
+pre-commit run --all-files
+```
+
+Pre-commit check results are also attached to your PR through integration with Github Action.

docs/contributing.rst

@@ -0,0 +1,26 @@
+# Format unmarshallers
+
+Based on `format` keyword, openapi-core can also unmarshal values to specific formats.
+
+Openapi-core comes with a set of built-in format unmarshallers, but it's also possible to add custom ones.
+
+Here's an example with the `usdate` format that converts a value to date object:
+
+``` python hl_lines="11"
+
+  from datetime import datetime
+
+  def unmarshal_usdate(value):
+     return datetime.strptime(value, "%m/%d/%y").date
+
+  extra_format_unmarshallers = {
+     'usdate': unmarshal_usdate,
+  }
+
+  config = Config(
+     extra_format_unmarshallers=extra_format_unmarshallers,
+  )
+  openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+  result = openapi.unmarshal_response(request, response)
+```

docs/customizations/extra_format_unmarshallers.md

@@ -0,0 +1,26 @@
+# Format validators
+
+OpenAPI defines a `format` keyword that hints at how a value should be interpreted, e.g. a `string` with the type `date` should conform to the RFC 3339 date format.
+
+OpenAPI comes with a set of built-in format validators, but it's also possible to add custom ones.
+
+Here's how you could add support for a `usdate` format that handles dates of the form MM/DD/YYYY:
+
+``` python hl_lines="11"
+
+  import re
+
+  def validate_usdate(value):
+     return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))
+
+  extra_format_validators = {
+     'usdate': validate_usdate,
+  }
+
+  config = Config(
+     extra_format_validators=extra_format_validators,
+  )
+  openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+  openapi.validate_response(request, response)
+```

docs/customizations/extra_format_unmarshallers.rst

@@ -0,0 +1,23 @@
+# Media type deserializers
+
+OpenAPI comes with a set of built-in media type deserializers such as: `application/json`, `application/xml`, `application/x-www-form-urlencoded` or `multipart/form-data`.
+
+You can also define your own ones. Pass custom defined media type deserializers dictionary with supported mimetypes as a key to `unmarshal_response` function:
+
+``` python hl_lines="11"
+def protobuf_deserializer(message):
+    feature = route_guide_pb2.Feature()
+    feature.ParseFromString(message)
+    return feature
+
+extra_media_type_deserializers = {
+    'application/protobuf': protobuf_deserializer,
+}
+
+config = Config(
+    extra_media_type_deserializers=extra_media_type_deserializers,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+result = openapi.unmarshal_response(request, response)
+```

docs/customizations/extra_format_validators.md

@@ -0,0 +1,3 @@
+# Customizations
+
+OpenAPI accepts `Config` object that allows users to customize the behavior validation and unmarshalling processes.

docs/customizations/extra_format_validators.rst

@@ -0,0 +1,20 @@
+# Request unmarshaller
+
+By default, request unmarshaller is selected based on detected specification version.
+
+In order to explicitly validate and unmarshal a:
+
+- OpenAPI 3.0 spec, import `V30RequestUnmarshaller`
+- OpenAPI 3.1 spec, import `V31RequestUnmarshaller` or `V31WebhookRequestUnmarshaller`
+
+``` python hl_lines="1 4"
+from openapi_core import V31RequestUnmarshaller
+
+config = Config(
+    request_unmarshaller_cls=V31RequestUnmarshaller,
+)
+openapi = OpenAPI.from_file_path('openapi.json', config=config)
+result = openapi.unmarshal_request(request)
+```
+
+You can also explicitly import `V3RequestUnmarshaller` which is a shortcut to the latest OpenAPI v3 version.