more convenient documentation of the api by using the sphinxcontrib.autohttp package

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')
 

compendium_v2/routes/api.py

-"""
-API Endpoints
-=========================
-
-.. contents:: :local:
-
-/api/
----------------------
-
-
-
-"""
 import logging
 
 from flask import Blueprint

compendium_v2/routes/default.py

-"""
-Default Endpoints
-=========================
-
-.. contents:: :local:
-
-/version
----------------------
-
-.. autofunction:: compendium_v2.routes.default.version
-
-"""
 import pkg_resources
 from flask import Blueprint, jsonify, render_template, Response
 

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:

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.

docs/source/publishers.rst

@@ -11,4 +11,3 @@ Publishers
 
 .. automodule:: compendium_v2.publishers.survey_publisher_2022
     :members:
-

requirements.txt

@@ -13,6 +13,7 @@ python-dotenv
 
 sphinx
 sphinx-rtd-theme
+sphinxcontrib-httpdomain
 tox
 
 mypy