diff --git a/.github/workflows/pythondoc.yml b/.github/workflows/pythondoc.yml index b45f8349..7d0f5f23 100644 --- a/.github/workflows/pythondoc.yml +++ b/.github/workflows/pythondoc.yml @@ -40,7 +40,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install Sphinx furo + pip install .[docs] make install - name: Generate docs run: | diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index ddf8c1f0..c4e7ae1a 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -47,6 +47,6 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install pytest syrupy + pip install .[dev] - name: Test run: make test diff --git a/Makefile b/Makefile index 8276dc0f..a12db61b 100644 --- a/Makefile +++ b/Makefile @@ -24,7 +24,7 @@ doc: cd docs && make html opendoc: - cd docs/build/html && python -m http.server 8765 + cd docs/build/html && python -m http.server 8765 -b 127.0.0.1 clean: rm -rf build/ dist/ *.egg-info .pytest_cache diff --git a/README.md b/README.md index 9a5af51b..f644d2f5 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,10 @@ Install with pip: `pip install spectree`. If you'd like for email fields to be v ### Examples -Check the [examples](/examples) folder. +Check the [examples](examples) folder. -* [flask example](/examples/flask_demo.py) -* [falcon example with logging when validation failed](/examples/falcon_demo.py) +* [flask example](examples/flask_demo.py) +* [falcon example with logging when validation failed](examples/falcon_demo.py) * [starlette example](examples/starlette_demo.py) ### Step by Step diff --git a/docs/source/conf.py b/docs/source/conf.py index 17c21297..c0e095a8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,6 +24,7 @@ # -- General configuration --------------------------------------------------- +autodoc_class_signature = "separated" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -32,6 +33,7 @@ "sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.githubpages", + "myst_parser", ] # Add any paths that contain templates here, relative to this directory. @@ -41,6 +43,8 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] +source_suffix = [".rst", ".md"] +language = "en" # -- Options for HTML output ------------------------------------------------- @@ -48,7 +52,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "furo" +html_theme = "shibuya" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..974f3bfd --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,35 @@ +```{eval-rst} +.. meta:: + :description lang=en: + SpecTree is an API spec validator and OpenAPI document generator for Python web frameworks. +``` + +```{include} ../../README.md +``` + +```{toctree} +--- +maxdepth: 2 +hidden: +caption: API reference +--- +spectree +config +response +models +utils +plugins +``` + +```{toctree} +--- +hidden: +caption: Project Links +--- + +GitHub +``` + +## Indices and tables + +- {ref}`genindex` diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 63c64d0a..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. spectree documentation master file, created by - sphinx-quickstart on Sun Dec 1 16:11:49 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -.. meta:: - :description lang=en: - SpecTree is an API spec validator and OpenAPI document generator for Python web frameworks. - -Welcome to spectree's documentation! -==================================== - -|GitHub Actions| |pypi| |versions| |Language grade: Python| -|Documentation Status| - -Yet another library to generate OpenAPI document and validate request & -response with Python annotations. - -Features --------- - -- Less boilerplate code, annotations are really easy-to-use -- Generate API document with `Redoc UI`_ or `Swagger UI`_ -- Validate query, JSON data, response data with `pydantic`_ -- Current support: - - - Flask - - Falcon (including Falcon ASGI) - - Starlette - -Quick Start ------------ - -Install with pip: ``pip install spectree``. If you'd like for email fields to be validated, use ``pip install spectree[email]``. - - -Examples -~~~~~~~~ - -Check the `examples`_ folder. - -Step by Step -~~~~~~~~~~~~ - -1. Define your data structure used in (query, json, headers, cookies, - resp) with ``pydantic.BaseModel`` -2. create ``spectree.SpecTree`` instance with the web framework name you - are using, like ``api = SpecTree('flask')`` -3. ``api.validate`` decorate the route with - - - ``query`` - - ``json`` - - ``headers`` - - ``cookies`` - - ``resp`` - - ``tags`` - -4. access these data with ``context(query, json, headers, cookies)`` (of - course, you can access these from the original place where the - framework offered) - - - flask: ``request.context`` - - falcon: ``req.context`` - - starlette: ``request.context`` - -5. register to the web application ``api.register(app)`` -6. check the document at URL location ``/apidoc/redoc`` or - ``/apidoc/swagger`` - -FAQ ---- - - ValidationError: missing field for headers - -The HTTP headers’ keys in Flask are capitalized, in Falcon are upper -cases, in Starlette are lower cases. - -.. _Redoc UI: https://github.com/Redocly/redoc -.. _Swagger UI: https://github.com/swagger-api/swagger-ui -.. _pydantic: https://github.com/samuelcolvin/pydantic/ -.. _examples: https://github.com/0b01001001/spectree/blob/master/examples - -.. |GitHub Actions| image:: https://github.com/0b01001001/spectree/workflows/Python%20package/badge.svg - :target: https://github.com/0b01001001/spectree/actions -.. |pypi| image:: https://img.shields.io/pypi/v/spectree.svg - :target: https://pypi.python.org/pypi/spectree -.. |versions| image:: https://img.shields.io/pypi/pyversions/spectree.svg - :target: https://github.com/0b01001001/spectree -.. |Language grade: Python| image:: https://img.shields.io/lgtm/grade/python/g/0b01001001/spectree.svg?logo=lgtm&logoWidth=18 - :target: https://lgtm.com/projects/g/0b01001001/spectree/context:python -.. |Documentation Status| image:: https://readthedocs.org/projects/spectree/badge/?version=latest - :target: https://spectree.readthedocs.io/en/latest/?badge=latest - - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - spectree - config - response - plugins - models - utils - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index 7153d125..5d0c3984 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,7 +50,8 @@ starlette = [ ] docs = [ "Sphinx", - "furo", + "shibuya", + "myst-parser", ] [project.urls] diff --git a/setup.py b/setup.py index de1217cf..261746b5 100644 --- a/setup.py +++ b/setup.py @@ -25,7 +25,8 @@ ], "docs": [ "Sphinx", - "furo", + "shibuya", + "myst-parser", ], }, ) diff --git a/spectree/spec.py b/spectree/spec.py index 49539cfb..33542f89 100644 --- a/spectree/spec.py +++ b/spectree/spec.py @@ -37,7 +37,8 @@ class SpecTree: """ Interface - :param str backend_name: choose from ('flask', 'falcon', 'falcon-asgi', 'starlette') + :param str backend_name: choose from + ('flask', 'quart', 'falcon', 'falcon-asgi', 'starlette') :param backend: a backend that inherit `SpecTree.plugins.base.BasePlugin`, this will override the `backend_name` if provided :param app: backend framework application instance (can be registered later) diff --git a/tests/test_response.py b/tests/test_response.py index 1ba509c2..daa24cda 100644 --- a/tests/test_response.py +++ b/tests/test_response.py @@ -112,7 +112,7 @@ def test_list_model(): model = resp.find_model(200) expect_model = gen_list_model(JSON) assert get_type_hints(model) == get_type_hints(expect_model) - assert type(model) == type(expect_model) + assert type(model) is type(expect_model) assert issubclass(model, BaseModel) data = [ {"name": "a", "limit": 1},