From 18b942fc97a9bb3ef94e2c7f2c438fb1699ae10a Mon Sep 17 00:00:00 2001 From: Rokas Maciulaitis Date: Wed, 24 Oct 2018 16:46:07 +0200 Subject: [PATCH] docs: better navigation and synced descriptions * Fix navigation. Harmonise title/description text in Python docstring and OpenAPI. Closes #95 Signed-off-by: Rokas Maciulaitis --- docs/conf.py | 20 ++++++++++++++------ docs/openapi.json | 1 + docs/restapi.rst | 1 + reana_job_controller/app.py | 23 ++++++++++++----------- 4 files changed, 28 insertions(+), 17 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ec92e561..cb56e15b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -61,6 +61,7 @@ 'embed': True, 'opts': { 'hide-loading': True, + 'hide-hostname': True, } } ] @@ -228,7 +229,7 @@ def get_name(full_module_name): Pull out the class/function name from the full_module_name. Split the full_module_name by "."'s """ - #split the full_module_name by "."'s + # split the full_module_name by "."'s module_name = ".".join(full_module_name.split(".")[:2]) function_name = full_module_name.split('.')[-1] return module_name, function_name @@ -239,13 +240,20 @@ def process_docstring(app, what, name, obj, options, lines): Deletes unnecessary docstring, saves summary and formats a hyperlink to redocs. """ - module_name,function_name = get_name(name) + module_name, function_name = get_name(name) + description = '' + operation_id = '' if what != "module" and module_name in rest_api_modules: - description = lines[0] - url = "`%s <_static/api.html#operation/%s>`_ "%(description,function_name) - #clearing the list of docstrings + for line in lines: + if "summary:" in line: + description = line.split("summary: ", 1)[1] + if "operationId:" in line: + operation_id = line.split('operationId: ', 1)[1] + url = "`%s <_static/api.html#operation/%s>`_" % (description, + operation_id) + # clearing the list of docstrings del lines[:] - #adding back description + # adding back description lines.append(url) diff --git a/docs/openapi.json b/docs/openapi.json index f742893d..5bb3c92b 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -154,6 +154,7 @@ "/jobs": { "get": { "description": "This resource is not expecting parameters and it will return a list representing all active jobs in JSON format.", + "operationId": "get_jobs", "produces": [ "application/json" ], diff --git a/docs/restapi.rst b/docs/restapi.rst index 54156f82..64a37d8f 100644 --- a/docs/restapi.rst +++ b/docs/restapi.rst @@ -8,3 +8,4 @@ Detailed REST API documentation can be found `here <_static/api.html>`_. .. automodule:: reana_job_controller.app :members: + :exclude-members: get_openapi_spec diff --git a/reana_job_controller/app.py b/reana_job_controller/app.py index bb7fc1ad..1770c63a 100644 --- a/reana_job_controller/app.py +++ b/reana_job_controller/app.py @@ -34,7 +34,7 @@ job_schema = Job() -def retrieve_job(job_id): +def _retrieve_job(job_id): """Retrieve job from DB by id. :param job_id: UUID which identifies the job to be retrieved. @@ -55,7 +55,7 @@ def retrieve_job(job_id): } -def retrieve_all_jobs(): +def _retrieve_all_jobs(): """Retrieve all jobs in the DB. :return: A list with all current job objects. @@ -80,7 +80,7 @@ def retrieve_all_jobs(): return job_list -def is_cached(job_spec, workflow_json, workflow_workspace): +def _is_cached(job_spec, workflow_json, workflow_workspace): """Check if job result exists in the cache.""" input_hash = calculate_job_input_hash(job_spec, workflow_json) workspace_hash = calculate_hash_of_dir(workflow_workspace) @@ -97,7 +97,7 @@ def is_cached(job_spec, workflow_json, workflow_workspace): return None -def job_exists(job_id): +def _job_exists(job_id): """Check if the job exists in the DB. :param job_id: UUID which identifies the job. @@ -106,7 +106,7 @@ def job_exists(job_id): return job_id in JOB_DB -def retrieve_job_logs(job_id): +def _retrieve_job_logs(job_id): """Retrieve job's logs. :param job_id: UUID which identifies the job. @@ -167,7 +167,7 @@ def check_if_cached(): job_spec = json.loads(request.args['job_spec']) workflow_json = json.loads(request.args['workflow_json']) workflow_workspace = request.args['workflow_workspace'] - result = is_cached(job_spec, workflow_json, workflow_workspace) + result = _is_cached(job_spec, workflow_json, workflow_workspace) if result: return jsonify({"cached": True, "result_path": result['result_path'], @@ -187,6 +187,7 @@ def get_jobs(): # noqa description: >- This resource is not expecting parameters and it will return a list representing all active jobs in JSON format. + operationId: get_jobs produces: - application/json responses: @@ -231,7 +232,7 @@ def get_jobs(): # noqa } } """ - return jsonify({"jobs": retrieve_all_jobs()}), 200 + return jsonify({"jobs": _retrieve_all_jobs()}), 200 @app.route('/jobs', methods=['POST']) @@ -384,8 +385,8 @@ def get_job(job_id): # noqa "message": >- The job cdcf48b1-c2f3-4693-8230-b066e088444c doesn't exist """ - if job_exists(job_id): - jobdict = retrieve_job(job_id) + if _job_exists(job_id): + jobdict = _retrieve_job(job_id) return jsonify(jobdict), 200 else: return jsonify({'message': 'The job {} doesn\'t exist' @@ -426,8 +427,8 @@ def get_logs(job_id): # noqa "message": >- The job cdcf48b1-c2f3-4693-8230-b066e088444c doesn't exist """ - if job_exists(job_id): - return retrieve_job_logs(job_id) + if _job_exists(job_id): + return _retrieve_job_logs(job_id) else: return jsonify({'message': 'The job {} doesn\'t exist' .format(job_id)}), 400