docs: use myst-parser and shibuya theme (0b01001001#332)

* docs: use myst-parser and shibuya theme

Signed-off-by: Keming <kemingy94@gmail.com>

* fix lint

Signed-off-by: Keming <kemingy94@gmail.com>

---------

Signed-off-by: Keming <kemingy94@gmail.com>

.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: |

.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

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

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

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,14 +43,16 @@
 # 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 -------------------------------------------------
 
 # 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,

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 <https://github.com/0b01001001/spectree>
+```
+
+## Indices and tables
+
+- {ref}`genindex`

pyproject.toml

@@ -50,7 +50,8 @@ starlette = [
 ]
 docs = [
     "Sphinx",
-    "furo",
+    "shibuya",
+    "myst-parser",
 ]
 
 [project.urls]

setup.py

@@ -25,7 +25,8 @@
         ],
         "docs": [
             "Sphinx",
-            "furo",
+            "shibuya",
+            "myst-parser",
         ],
     },
 )

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)

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},