From 5cb0824c09447199ac261acbf1745d87093d9add Mon Sep 17 00:00:00 2001
From: p1c2u <maciag.artur@gmail.com>
Date: Mon, 12 Feb 2024 10:33:15 +0000
Subject: [PATCH] Reference code API docs

---
 docs/api/index.rst   |  9 +++++++++
 docs/api/openapi.rst |  5 +++++
 docs/conf.py         |  1 +
 docs/index.rst       |  1 +
 openapi_core/app.py  | 16 +++++++++++++++-
 poetry.lock          | 23 +++++++++++++++++++++--
 pyproject.toml       |  1 +
 7 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 docs/api/index.rst
 create mode 100644 docs/api/openapi.rst

diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644
index 00000000..f70b04bc
--- /dev/null
+++ b/docs/api/index.rst
@@ -0,0 +1,9 @@
+API Reference
+=============
+
+Documentation with information of functions, classes or methods and all other parts of the OpenAPI-core public API.
+
+.. toctree::
+    :maxdepth: 1
+
+    openapi
diff --git a/docs/api/openapi.rst b/docs/api/openapi.rst
new file mode 100644
index 00000000..2ed3cd43
--- /dev/null
+++ b/docs/api/openapi.rst
@@ -0,0 +1,5 @@
+`OpenAPI` class
+===============
+
+.. autoclass:: openapi_core.OpenAPI
+    :members:
diff --git a/docs/conf.py b/docs/conf.py
index cb6623a2..764b0671 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -38,6 +38,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinx_autodoc_typehints",
     "sphinx_immaterial",
 ]
 
diff --git a/docs/index.rst b/docs/index.rst
index 24eacced..b23e8d0a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ openapi-core
     customizations/index
     security
     extensions
+    api/index
     contributing
 
 Openapi-core is a Python library that adds client-side and server-side support
diff --git a/openapi_core/app.py b/openapi_core/app.py
index 5a2c5588..9af8f8e6 100644
--- a/openapi_core/app.py
+++ b/openapi_core/app.py
@@ -71,7 +71,17 @@
 
 
 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,
@@ -90,6 +100,7 @@ def __init__(
     def from_dict(
         cls, data: Schema, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a dictionary."""
         sp = SchemaPath.from_dict(data)
         return cls(sp, config=config)
 
@@ -97,6 +108,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)
 
@@ -104,6 +116,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)
 
@@ -111,6 +124,7 @@ def from_file_path(
     def from_file(
         cls, fileobj: SupportsRead, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a file object."""
         sp = SchemaPath.from_file(fileobj)
         return cls(sp, config=config)
 
diff --git a/poetry.lock b/poetry.lock
index 4e24afa4..067ee3f3 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.6.1 and should not be changed by hand.
 
 [[package]]
 name = "aiohttp"
@@ -2158,6 +2158,25 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-simplify", "isort", "mypy (>=0.990)", "ruff", "sphinx-lint", "types-requests"]
 test = ["cython", "filelock", "html5lib", "pytest (>=4.6)"]
 
+[[package]]
+name = "sphinx-autodoc-typehints"
+version = "2.0.0"
+description = "Type hints (PEP 484) support for the Sphinx autodoc extension"
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "sphinx_autodoc_typehints-2.0.0-py3-none-any.whl", hash = "sha256:12c0e161f6fe191c2cdfd8fa3caea271f5387d9fbc67ebcd6f4f1f24ce880993"},
+    {file = "sphinx_autodoc_typehints-2.0.0.tar.gz", hash = "sha256:7f2cdac2e70fd9787926b6e9e541cd4ded1e838d2b46fda2a1bb0a75ec5b7f3a"},
+]
+
+[package.dependencies]
+sphinx = ">=7.1.2"
+
+[package.extras]
+docs = ["furo (>=2023.9.10)"]
+numpy = ["nptyping (>=2.5)"]
+testing = ["covdefaults (>=2.3)", "coverage (>=7.3.2)", "diff-cover (>=8.0.1)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "sphobjinv (>=2.3.1)", "typing-extensions (>=4.8)"]
+
 [[package]]
 name = "sphinx-immaterial"
 version = "0.11.10"
@@ -2533,4 +2552,4 @@ starlette = ["aioitertools", "starlette"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8.0"
-content-hash = "09d51553f494e21e03261f7c996c978580e73472731c1b64ac17378bbfe70cb4"
+content-hash = "8be891b44db9a4ac3f74c4374abf34b66ddb373920d3ef43a848a33de2f29342"
diff --git a/pyproject.toml b/pyproject.toml
index a3b1dfa2..3e6852c4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -112,6 +112,7 @@ pyflakes = "^3.1.0"
 [tool.poetry.group.docs.dependencies]
 sphinx = ">=5.3,<8.0"
 sphinx-immaterial = "^0.11.0"
+sphinx-autodoc-typehints = "^2.0.0"
 
 [tool.pytest.ini_options]
 addopts = """