documentation improvements

.github/workflows/build-docs.yml

@@ -0,0 +1,54 @@
+name: Build documentation
+
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Get full Python version
+        id: full-python-version
+        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
+
+      - name: Bootstrap poetry
+        run: |
+          curl -sL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python - -y
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Configure poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Set up cache
+        uses: actions/cache@v2
+        id: cache
+        with:
+          path: .venv
+          key: venv-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Ensure cache is healthy
+        if: steps.cache.outputs.cache-hit == 'true'
+        run: timeout 10s poetry run pip --version || rm -rf .venv
+
+      - name: Install dependencies
+        run: poetry install -E docs
+
+      - 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
+
+      - uses: actions/upload-artifact@v2
+        name: Upload docs as artifact
+        with:
+          name: docs-html
+          path: './docs/_build/html'
+          if-no-files-found: error

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: all
+
+python:
+  version: 3.8
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.rst

@@ -0,0 +1 @@
+Please read the `Contributing <https://openapi-schema-validator.readthedocs.io/en/latest/contributing.html>`__ guidelines in the documentation site.

README.rst

@@ -23,27 +23,32 @@ Openapi-schema-validator is a Python library that validates schema against:
 * `OpenAPI Schema Specification v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject>`__ which is an extended subset of the `JSON Schema Specification Wright Draft 00 <http://json-schema.org/>`__.
 * `OpenAPI Schema Specification v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schemaObject>`__ which is an extended superset of the `JSON Schema Specification Draft 2020-12 <http://json-schema.org/>`__.
 
+
+Documentation
+#############
+
+Check documentation to see more details about the features. All documentation is in the "docs" directory and online at `openapi-schema-validator.readthedocs.io <https://openapi-schema-validator.readthedocs.io>`__
+
+
 Installation
 ############
 
 Recommended way (via pip):
 
-::
+.. code-block:: console
 
-    $ pip install openapi-schema-validator
+   pip install openapi-schema-validator
 
 Alternatively you can download the code and install from the repository:
 
-.. code-block:: bash
+.. code-block:: console
 
-   $ pip install -e git+https://github.com/p1c2u/openapi-schema-validator.git#egg=openapi_schema_validator
+   pip install -e git+https://github.com/p1c2u/openapi-schema-validator.git#egg=openapi_schema_validator
 
 
 Usage
 #####
 
-By default, the latest OpenAPI schema syntax is expected.
-
 To validate an OpenAPI v3.1 schema:
 
 .. code-block:: python
@@ -92,151 +97,9 @@ To validate an OpenAPI v3.1 schema:
        ...
    ValidationError: Additional properties are not allowed ('city' was unexpected)
 
-if you want to disambiguate the expected schema version, import and use ``OAS31Validator``:
-
-.. code-block:: python
-
-   from openapi_schema_validator import OAS31Validator
-
-   validate({"name": "John", "age": 23}, schema, cls=OAS31Validator)
-
-In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` instead of ``OAS31Validator``.
-
-.. code-block:: python
-
-   from openapi_schema_validator import OAS30Validator
-
-   # A sample schema
-   schema = {
-       "type": "object",
-       "required": [
-          "name"
-       ],
-       "properties": {
-           "name": {
-               "type": "string"
-           },
-           "age": {
-               "type": "integer",
-               "format": "int32",
-               "minimum": 0,
-               "nullable": True,
-           },
-           "birth-date": {
-               "type": "string",
-               "format": "date",
-           }
-       },
-       "additionalProperties": False,
-   }
-
-   validate({"name": "John", "age": None}, schema, cls=OAS30Validator)
-
-In order to validate read/write context in OpenAPI 3.0 schema, import and use ``OAS30ReadValidator`` or ``OAS30WriteValidator``.
-
-.. code-block:: python
-
-   from openapi_schema_validator import OAS30WriteValidator
-
-   # A sample schema
-   schema = {
-       "type": "object",
-       "required": [
-          "name"
-       ],
-       "properties": {
-           "name": {
-               "type": "string"
-           },
-           "age": {
-               "type": "integer",
-               "format": "int32",
-               "minimum": 0,
-               "readOnly": True,
-           },
-           "birth-date": {
-               "type": "string",
-               "format": "date",
-           }
-       },
-       "additionalProperties": False,
-   }
-
-   validate({"name": "John", "age": 23}, schema, cls=OAS30WriteValidator)
-
-   Traceback (most recent call last):
-       ...
-   ValidationError: Tried to write read-only property with 23
-
-Format check
-************
-
-You can also check format for primitive types
-
-.. code-block:: python
-
-   from openapi_schema_validator import oas31_format_checker
-
-   validate({"name": "John", "birth-date": "-12"}, schema, format_checker=oas31_format_checker)
-
-   Traceback (most recent call last):
-       ...
-   ValidationError: '-12' is not a 'date'
-
-References
-**********
-
-You can resolve JSON references by passing custon reference resolver
-
-.. code-block:: python
-
-   from jsonschema.validators import RefResolver
-
-   # A schema with reference
-   schema = {
-       "type" : "object",
-       "required": [
-          "name"
-       ],
-       "properties": {
-           "name": {
-               "$ref": "#/components/schemas/Name"
-           },
-           "age": {
-               "$ref": "#/components/schemas/Age"
-           },
-           "birth-date": {
-               "$ref": "#/components/schemas/BirthDate"
-           }
-       },
-       "additionalProperties": False,
-   }
-   # Referenced schemas
-   schemas = {
-       "components": {
-           "schemas": {
-               "Name": {
-                   "type": "string"
-               },
-               "Age": {
-                   "type": "integer",
-                   "format": "int32",
-                   "minimum": 0,
-                   "nullable": True,
-               },
-               "BirthDate": {
-                   "type": "string",
-                   "format": "date",
-               }
-           },
-       },
-   }
-
-   ref_resolver = RefResolver.from_schema(schemas)
-
-   validate({"name": "John", "age": 23}, schema, resolver=ref_resolver)
+By default, the latest OpenAPI schema syntax is expected.
 
-For more information about reference resolver see `Resolving JSON References <https://python-jsonschema.readthedocs.io/en/stable/references/>`__
+For more details read about `Validation <https://openapi-schema-validator.readthedocs.io/en/latest/validation.html>`__.
 
 Related projects
 ################

docs/conf.py

@@ -0,0 +1,64 @@
+import openapi_schema_validator
+
+project = "openapi-schema-validator"
+copyright = "2023, Artur Maciag"
+author = "Artur Maciag"
+
+release = openapi_schema_validator.__version__
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
+    "sphinx_immaterial",
+]
+
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_immaterial"
+
+html_static_path = []
+
+html_title = "openapi-schema-validator"
+
+html_theme_options = {
+    "analytics": {
+        "provider": "google",
+        "property": "G-11RDPBZ7EJ",
+    },
+    "repo_url": "https://github.com/p1c2u/openapi-schema-validator/",
+    "repo_name": "openapi-schema-validator",
+    "repo_type": "github",
+    "icon": {
+        "repo": "fontawesome/brands/github-alt",
+        "edit": "material/file-edit-outline",
+    },
+    "palette": [
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "lime",
+            "accent": "amber",
+            "scheme": "slate",
+            "toggle": {
+                "icon": "material/toggle-switch",
+                "name": "Switch to light mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "lime",
+            "accent": "amber",
+            "toggle": {
+                "icon": "material/toggle-switch-off-outline",
+                "name": "Switch to dark mode",
+            },
+        },
+    ],
+    "globaltoc_collapse": False,
+}