From df9908aec09d1f9c9237018b438e3abd1b954c00 Mon Sep 17 00:00:00 2001
From: Remco Tukker <remco.tukker@geant.org>
Date: Fri, 28 Apr 2023 00:21:47 +0200
Subject: [PATCH] more convenient documentation of the api by using the
sphinxcontrib.autohttp package
---
compendium_v2/__init__.py | 27 +++++++++++++++++----------
compendium_v2/routes/api.py | 12 ------------
compendium_v2/routes/default.py | 12 ------------
docs/source/api.rst | 14 ++++----------
docs/source/conf.py | 4 +++-
docs/source/publishers.rst | 1 -
requirements.txt | 1 +
7 files changed, 25 insertions(+), 46 deletions(-)
diff --git a/compendium_v2/__init__.py b/compendium_v2/__init__.py
index 69673b9f..622565f2 100644
--- a/compendium_v2/__init__.py
+++ b/compendium_v2/__init__.py
@@ -17,6 +17,22 @@ def migrate_database(config: dict) -> None:
migration_utils.upgrade(dsn)
+def _create_app(app_config) -> Flask:
+ # used by sphinx to create documentation without config and db migrations
+ app = Flask(__name__)
+ CORS(app)
+
+ app.config['CONFIG_PARAMS'] = app_config
+
+ from compendium_v2.routes import default
+ app.register_blueprint(default.routes, url_prefix='/')
+
+ from compendium_v2.routes import api
+ app.register_blueprint(api.routes, url_prefix='/api')
+
+ return app
+
+
def create_app() -> Flask:
"""
overrides default settings with those found
@@ -30,16 +46,7 @@ def create_app() -> Flask:
with open(os.environ['SETTINGS_FILENAME']) as f:
app_config = config.load(f)
- app = Flask(__name__)
- CORS(app)
-
- app.config['CONFIG_PARAMS'] = app_config
-
- from compendium_v2.routes import default
- app.register_blueprint(default.routes, url_prefix='/')
-
- from compendium_v2.routes import api
- app.register_blueprint(api.routes, url_prefix='/api')
+ app = _create_app(app_config)
logging.info('Flask app initialized')
diff --git a/compendium_v2/routes/api.py b/compendium_v2/routes/api.py
index e4fd4104..ec39ab77 100644
--- a/compendium_v2/routes/api.py
+++ b/compendium_v2/routes/api.py
@@ -1,15 +1,3 @@
-"""
-API Endpoints
-=========================
-
-.. contents:: :local:
-
-/api/
----------------------
-
-
-
-"""
import logging
from flask import Blueprint
diff --git a/compendium_v2/routes/default.py b/compendium_v2/routes/default.py
index eaf14206..9d2ed2f9 100644
--- a/compendium_v2/routes/default.py
+++ b/compendium_v2/routes/default.py
@@ -1,15 +1,3 @@
-"""
-Default Endpoints
-=========================
-
-.. contents:: :local:
-
-/version
----------------------
-
-.. autofunction:: compendium_v2.routes.default.version
-
-"""
import pkg_resources
from flask import Blueprint, jsonify, render_template, Response
diff --git a/docs/source/api.rst b/docs/source/api.rst
index 1db2969a..bd4f2469 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -9,14 +9,8 @@ Responses to valid requests are returned as JSON messages.
The server will therefore return an error unless
`application/json` is in the `Accept` request header field.
-HTTP communication and JSON grammar details are
-beyond the scope of this document.
-Please refer to [RFC 2616](https://tools.ietf.org/html/rfc2616)
-and www.json.org for more details.
-
-.. contents:: :local:
-
-.. automodule:: compendium_v2.routes.default
-
-.. automodule:: compendium_v2.routes.api
+.. qrefflask:: compendium_v2:_create_app(None)
+ :autoquickref:
+.. autoflask:: compendium_v2:_create_app(None)
+ :undoc-static:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 48b40e92..62ba0d56 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -73,7 +73,9 @@ release = '0.0'
extensions = [
'sphinx_rtd_theme',
'sphinx.ext.autodoc',
- 'sphinx.ext.coverage'
+ 'sphinx.ext.coverage',
+ 'sphinxcontrib.autohttp.flask',
+ 'sphinxcontrib.autohttp.flaskqref'
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/publishers.rst b/docs/source/publishers.rst
index 011de02f..85818b3f 100644
--- a/docs/source/publishers.rst
+++ b/docs/source/publishers.rst
@@ -11,4 +11,3 @@ Publishers
.. automodule:: compendium_v2.publishers.survey_publisher_2022
:members:
-
diff --git a/requirements.txt b/requirements.txt
index 1dc1ed6b..f409d9fa 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -13,6 +13,7 @@ python-dotenv
sphinx
sphinx-rtd-theme
+sphinxcontrib-httpdomain
tox
mypy
--
GitLab