Markdown documentation

.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

README.rst → README.md

@@ -1,45 +1,45 @@
-************
-openapi-core
-************
-
-.. image:: https://img.shields.io/pypi/v/openapi-core.svg
-     :target: https://pypi.python.org/pypi/openapi-core
-.. image:: https://travis-ci.org/python-openapi/openapi-core.svg?branch=master
-     :target: https://travis-ci.org/python-openapi/openapi-core
-.. image:: https://img.shields.io/codecov/c/github/python-openapi/openapi-core/master.svg?style=flat
-     :target: https://codecov.io/github/python-openapi/openapi-core?branch=master
-.. image:: https://img.shields.io/pypi/pyversions/openapi-core.svg
-     :target: https://pypi.python.org/pypi/openapi-core
-.. image:: https://img.shields.io/pypi/format/openapi-core.svg
-     :target: https://pypi.python.org/pypi/openapi-core
-.. image:: https://img.shields.io/pypi/status/openapi-core.svg
-     :target: https://pypi.python.org/pypi/openapi-core
-
-About
-#####
+# openapi-core
+
+<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
+    <img src="https://img.shields.io/pypi/v/openapi-core.svg" alt="Package version">
+</a>
+<a href="https://travis-ci.org/python-openapi/openapi-core" target="_blank">
+    <img src="https://travis-ci.org/python-openapi/openapi-core.svg?branch=master" alt="Continuous Integration">
+</a>
+<a href="https://codecov.io/github/python-openapi/openapi-core?branch=master" target="_blank">
+    <img src="https://img.shields.io/codecov/c/github/python-openapi/openapi-core/master.svg?style=flat" alt="Tests coverage">
+</a>
+<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/openapi-core.svg" alt="Python versions">
+</a>
+<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
+    <img src="https://img.shields.io/pypi/format/openapi-core.svg" alt="Package format">
+</a>
+<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
+    <img src="https://img.shields.io/pypi/status/openapi-core.svg" alt="Development status">
+</a>
+
+## About
 
 Openapi-core is a Python library that adds client-side and server-side support
 for the `OpenAPI v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md>`__
 and `OpenAPI v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md>`__ specification.
 
 
-Key features
-############
+## Key features
 
 * **Validation** and **unmarshalling** of request and response data (including webhooks)
 * **Integration** with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette)
 * Customization with media type **deserializers** and format **unmarshallers**
 * **Security** data providers (API keys, Cookie, Basic and Bearer HTTP authentications)
 
 
-Documentation
-#############
+## Documentation
 
 Check documentation to see more details about the features. All documentation is in the "docs" directory and online at `openapi-core.readthedocs.io <https://openapi-core.readthedocs.io>`__
 
 
-Installation
-############
+## Installation
 
 Recommended way (via pip):
 
@@ -54,8 +54,7 @@ Alternatively you can download the code and install from the repository:
     pip install -e git+https://github.com/python-openapi/openapi-core.git#egg=openapi_core
 
 
-First steps
-###########
+## First steps
 
 Firstly create your OpenAPI object.
 
@@ -93,8 +92,8 @@ For more details read about `Unmarshalling <https://openapi-core.readthedocs.io/
 If you just want to validate your request/response data without unmarshalling, read about `Validation <https://openapi-core.readthedocs.io/en/latest/validation.html>`__ instead.
 
 
-Related projects
-################
+## Related projects
+
 * `openapi-spec-validator <https://github.com/python-openapi/openapi-spec-validator>`__
     Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger), OpenAPI 3.0 and OpenAPI 3.1 specification. The validator aims to check for full compliance with the Specification.
 * `openapi-schema-validator <https://github.com/python-openapi/openapi-schema-validator>`__
@@ -106,8 +105,6 @@ Related projects
 * `tornado-openapi3 <https://github.com/correl/tornado-openapi3>`__
     Tornado OpenAPI 3 request and response validation library.
 
-
-License
-#######
+# License
 
 The project is under the terms of BSD 3-Clause License.

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.