From 088ceda7692f6746ea101e7588f2a1a5fe06405c Mon Sep 17 00:00:00 2001
From: p1c2u <maciag.artur@gmail.com>
Date: Sun, 15 Sep 2024 12:17:33 +0000
Subject: [PATCH] Reference docs

---
 docs/reference/index.md   |  3 +++
 docs/reference/openapi.md |  9 +++++++++
 mkdocs.yml                | 10 ++++++++++
 openapi_core/app.py       | 27 +++++++++++++++++++++++++--
 poetry.lock               | 17 ++++++++++++++++-
 pyproject.toml            |  1 +
 6 files changed, 64 insertions(+), 3 deletions(-)
 create mode 100644 docs/reference/index.md
 create mode 100644 docs/reference/openapi.md

diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 00000000..6e0465fd
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,3 @@
+# Reference
+
+Documentation with information of functions, classes or methods and all other parts of the OpenAPI-core public API.
diff --git a/docs/reference/openapi.md b/docs/reference/openapi.md
new file mode 100644
index 00000000..118bfc37
--- /dev/null
+++ b/docs/reference/openapi.md
@@ -0,0 +1,9 @@
+# `OpenAPI` class
+
+::: openapi_core.OpenAPI
+    options:
+        members:
+            - from_dict
+            - from_path
+            - from_file_path
+            - from_file
diff --git a/mkdocs.yml b/mkdocs.yml
index 7fcd9ff8..1e5c162b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -46,6 +46,13 @@ theme:
     - toc.follow
 repo_name: python-openapi/openapi-core
 repo_url: https://github.com/python-openapi/openapi-core
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            extensions:
+              - griffe_typingdoc
 nav:
   - OpenAPI-core: index.md
   - unmarshalling.md
@@ -75,6 +82,9 @@ nav:
     - customizations/extra_format_unmarshallers.md
   - security.md
   - extensions.md
+  - Reference:
+    - reference/index.md
+    - reference/openapi.md
   - contributing.md
 markdown_extensions:
   - admonition
diff --git a/openapi_core/app.py b/openapi_core/app.py
index cd511995..c40cc965 100644
--- a/openapi_core/app.py
+++ b/openapi_core/app.py
@@ -14,6 +14,8 @@
 from openapi_spec_validator.versions.datatypes import SpecVersion
 from openapi_spec_validator.versions.exceptions import OpenAPIVersionNotFound
 from openapi_spec_validator.versions.shortcuts import get_spec_version
+from typing_extensions import Annotated
+from typing_extensions import Doc
 
 from openapi_core.configurations import Config
 from openapi_core.exceptions import SpecError
@@ -72,11 +74,28 @@
 
 
 class OpenAPI:
-    """OpenAPI class."""
+    """`OpenAPI` application class, the main entrypoint class for OpenAPI-core.
+
+    Read more information, in the 
+    [OpenAPI-core docs for First Steps](https://openapi-core.readthedocs.io/#first-steps).
+
+    Import :class:`OpenAPI` class from the main `openapi_core` module::
+
+        from openapi_core import OpenAPI
+
+        app = OpenAPI(spec)
+    """
 
     def __init__(
         self,
-        spec: SchemaPath,
+        spec: Annotated[
+            SchemaPath,
+            Doc(
+                """
+                OpenAPI specification schema path object.
+                """
+            ),
+        ],
         config: Optional[Config] = None,
     ):
         if not isinstance(spec, SchemaPath):
@@ -91,6 +110,7 @@ def __init__(
     def from_dict(
         cls, data: Schema, config: Optional[Config] = None, base_uri: str = ""
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a dictionary."""
         sp = SchemaPath.from_dict(data, base_uri=base_uri)
         return cls(sp, config=config)
 
@@ -98,6 +118,7 @@ def from_dict(
     def from_path(
         cls, path: Path, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a path object."""
         sp = SchemaPath.from_path(path)
         return cls(sp, config=config)
 
@@ -105,6 +126,7 @@ def from_path(
     def from_file_path(
         cls, file_path: str, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a file path string."""
         sp = SchemaPath.from_file_path(file_path)
         return cls(sp, config=config)
 
@@ -115,6 +137,7 @@ def from_file(
         config: Optional[Config] = None,
         base_uri: str = "",
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a file object."""
         sp = SchemaPath.from_file(fileobj, base_uri=base_uri)
         return cls(sp, config=config)
 
diff --git a/poetry.lock b/poetry.lock
index 25fba203..ecd8cd7c 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -898,6 +898,21 @@ files = [
 astunparse = {version = ">=1.6", markers = "python_version < \"3.9\""}
 colorama = ">=0.4"
 
+[[package]]
+name = "griffe-typingdoc"
+version = "0.2.7"
+description = "Griffe extension for PEP 727 – Documentation Metadata in Typing."
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "griffe_typingdoc-0.2.7-py3-none-any.whl", hash = "sha256:74a825df32fc87fcae2f221df5c5524dca23155cd3c04ec9fa46493669d3cf54"},
+    {file = "griffe_typingdoc-0.2.7.tar.gz", hash = "sha256:800841e99f8844ea3c1fae80b19bede7d8eed4195a2586f5db753f7a73f4931d"},
+]
+
+[package.dependencies]
+griffe = ">=0.49"
+typing-extensions = ">=4.7"
+
 [[package]]
 name = "h11"
 version = "0.14.0"
@@ -2814,4 +2829,4 @@ starlette = ["aioitertools", "starlette"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8.0"
-content-hash = "cbc13c34f209528f9850b380b1a6c0781b870755031144a13792ef4cd85add09"
+content-hash = "806905385dfffe416e6e916963c22d2446f8d5036a072c04e3d0599ad6a062f8"
diff --git a/pyproject.toml b/pyproject.toml
index d58023a0..c6dd80da 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -117,6 +117,7 @@ fastapi = ">=0.111,<0.115"
 mkdocs = "^1.6.1"
 mkdocstrings = {extras = ["python"], version = "^0.26.1"}
 mkdocs-material = "^9.5.34"
+griffe-typingdoc = "^0.2.7"
 
 [tool.pytest.ini_options]
 addopts = """