Skip to content

Commit 6fe9de8

Browse files
p1c2up1c2u
committed
Markdown documentation
1 parent 34372f7 commit 6fe9de8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+1709
-1687
lines changed

‎.github/workflows/build-docs.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,11 @@ jobs:
4242

4343
- name: Build documentation
4444
run: |
45-
poetry run python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html -n -W
45+
poetry run python -m mkdocs build --clean --site-dir ./_build/html --config-file mkdocs.yml
4646
4747
- uses: actions/upload-artifact@v4
4848
name: Upload docs as artifact
4949
with:
5050
name: docs-html
51-
path: './docs/_build/html'
51+
path: './_build/html'
5252
if-no-files-found: error

‎.readthedocs.yaml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
33
version: 2
44

5-
# Build documentation in the docs/ directory with Sphinx
6-
sphinx:
7-
configuration: docs/conf.py
5+
# Build documentation with Mkdocs
6+
mkdocs:
7+
configuration: mkdocs.yml
88

99
# Optionally build your docs in additional formats such as PDF and ePub
1010
formats: all

‎README.rst renamed to ‎README.md

Lines changed: 29 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,45 @@
1-
************
2-
openapi-core
3-
************
4-
5-
.. image:: https://img.shields.io/pypi/v/openapi-core.svg
6-
:target: https://pypi.python.org/pypi/openapi-core
7-
.. image:: https://travis-ci.org/python-openapi/openapi-core.svg?branch=master
8-
:target: https://travis-ci.org/python-openapi/openapi-core
9-
.. image:: https://img.shields.io/codecov/c/github/python-openapi/openapi-core/master.svg?style=flat
10-
:target: https://codecov.io/github/python-openapi/openapi-core?branch=master
11-
.. image:: https://img.shields.io/pypi/pyversions/openapi-core.svg
12-
:target: https://pypi.python.org/pypi/openapi-core
13-
.. image:: https://img.shields.io/pypi/format/openapi-core.svg
14-
:target: https://pypi.python.org/pypi/openapi-core
15-
.. image:: https://img.shields.io/pypi/status/openapi-core.svg
16-
:target: https://pypi.python.org/pypi/openapi-core
17-
18-
About
19-
#####
1+
# openapi-core
2+
3+
<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
4+
<img src="https://img.shields.io/pypi/v/openapi-core.svg" alt="Package version">
5+
</a>
6+
<a href="https://travis-ci.org/python-openapi/openapi-core" target="_blank">
7+
<img src="https://travis-ci.org/python-openapi/openapi-core.svg?branch=master" alt="Continuous Integration">
8+
</a>
9+
<a href="https://codecov.io/github/python-openapi/openapi-core?branch=master" target="_blank">
10+
<img src="https://img.shields.io/codecov/c/github/python-openapi/openapi-core/master.svg?style=flat" alt="Tests coverage">
11+
</a>
12+
<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
13+
<img src="https://img.shields.io/pypi/pyversions/openapi-core.svg" alt="Python versions">
14+
</a>
15+
<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
16+
<img src="https://img.shields.io/pypi/format/openapi-core.svg" alt="Package format">
17+
</a>
18+
<a href="https://pypi.python.org/pypi/openapi-core" target="_blank">
19+
<img src="https://img.shields.io/pypi/status/openapi-core.svg" alt="Development status">
20+
</a>
21+
22+
## About
2023

2124
Openapi-core is a Python library that adds client-side and server-side support
2225
for the `OpenAPI v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md>`__
2326
and `OpenAPI v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md>`__ specification.
2427

2528

26-
Key features
27-
############
29+
## Key features
2830

2931
* **Validation** and **unmarshalling** of request and response data (including webhooks)
3032
* **Integration** with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette)
3133
* Customization with media type **deserializers** and format **unmarshallers**
3234
* **Security** data providers (API keys, Cookie, Basic and Bearer HTTP authentications)
3335

3436

35-
Documentation
36-
#############
37+
## Documentation
3738

3839
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>`__
3940

4041

41-
Installation
42-
############
42+
## Installation
4343

4444
Recommended way (via pip):
4545

@@ -54,8 +54,7 @@ Alternatively you can download the code and install from the repository:
5454
pip install -e git+https://github.com/python-openapi/openapi-core.git#egg=openapi_core
5555

5656

57-
First steps
58-
###########
57+
## First steps
5958

6059
Firstly create your OpenAPI object.
6160

@@ -93,8 +92,8 @@ For more details read about `Unmarshalling <https://openapi-core.readthedocs.io/
9392
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.
9493

9594

96-
Related projects
97-
################
95+
## Related projects
96+
9897
* `openapi-spec-validator <https://github.com/python-openapi/openapi-spec-validator>`__
9998
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.
10099
* `openapi-schema-validator <https://github.com/python-openapi/openapi-schema-validator>`__
@@ -106,8 +105,6 @@ Related projects
106105
* `tornado-openapi3 <https://github.com/correl/tornado-openapi3>`__
107106
Tornado OpenAPI 3 request and response validation library.
108107

109-
110-
License
111-
#######
108+
# License
112109

113110
The project is under the terms of BSD 3-Clause License.

‎docs/conf.py

Lines changed: 0 additions & 105 deletions
This file was deleted.

‎docs/contributing.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
hide:
3+
- navigation
4+
---
5+
6+
# Contributing
7+
8+
Firstly, thank you all for taking the time to contribute.
9+
10+
The following section describes how you can contribute to the openapi-core project on GitHub.
11+
12+
## Reporting bugs
13+
14+
### Before you report
15+
16+
- Check whether your issue does not already exist in the [Issue tracker](https://github.com/python-openapi/openapi-core/issues).
17+
- Make sure it is not a support request or question better suited for [Discussion board](https://github.com/python-openapi/openapi-core/discussions).
18+
19+
### How to submit a report
20+
21+
- Include clear title.
22+
- Describe your runtime environment with exact versions you use.
23+
- Describe the exact steps which reproduce the problem, including minimal code snippets.
24+
- Describe the behavior you observed after following the steps, pasting console outputs.
25+
- Describe expected behavior to see and why, including links to documentations.
26+
27+
## Code contribution
28+
29+
### Prerequisites
30+
31+
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:
32+
33+
```console
34+
poetry config virtualenvs.in-project true
35+
```
36+
37+
### Setup
38+
39+
To create a development environment and install the runtime and development dependencies, run:
40+
41+
```console
42+
poetry install
43+
```
44+
45+
Then enter the virtual environment created by Poetry:
46+
47+
```console
48+
poetry shell
49+
```
50+
51+
### Static checks
52+
53+
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.
54+
55+
To turn on pre-commit checks for commit operations in git, enter:
56+
57+
```console
58+
pre-commit install
59+
```
60+
61+
To run all checks on your staged files, enter:
62+
63+
```console
64+
pre-commit run
65+
```
66+
67+
To run all checks on all files, enter:
68+
69+
```console
70+
pre-commit run --all-files
71+
```
72+
73+
Pre-commit check results are also attached to your PR through integration with Github Action.

‎docs/contributing.rst

Lines changed: 0 additions & 76 deletions
This file was deleted.

0 commit comments

Comments
 (0)