From 0128dc5ffee735f04fb6aae197ccaa1255be8cfe Mon Sep 17 00:00:00 2001 From: Luiggi Tenorio Date: Mon, 22 Apr 2024 15:12:58 +0200 Subject: [PATCH 1/3] sphinx setup --- docs/.gitkeep | 0 docs/Makefile | 208 +++++++++++++++++++++++++++++++++ docs/requirements.txt | 6 + docs/source/_static/Logo.svg | 67 +++++++++++ docs/source/_static/custom.css | 19 +++ docs/source/conf.py | 24 ++++ docs/source/index.rst | 5 + 7 files changed, 329 insertions(+) delete mode 100644 docs/.gitkeep create mode 100644 docs/Makefile create mode 100644 docs/requirements.txt create mode 100644 docs/source/_static/Logo.svg create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/.gitkeep b/docs/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..0ba74d9d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,208 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = sphinx-build +PAPER = +SOURCEDIR = source +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean watch html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " watch to make standalone HTML files and watch for changes" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +watch: clean + @echo + @echo "Building and watching for changes in the documentation." + sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" \ + -b html \ + --port 8099 \ + --ignore='**venv' \ + --ignore='**.gitlab' \ + --ignore='*.egg-info' \ + --ignore='bin' \ + --ignore='**_includes/**/*.txt' \ + --watch='autosubmit' \ + $(SPHINXOPTS) $(O) + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/autosubmit.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/autosubmit.qhc" + +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/autosubmit" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/autosubmit" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..5deaf0fc --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +livereload +pydata-sphinx-theme==0.15.* +sphinx==5.* +sphinx-autobuild==2021.3.* +sphinx_rtd_theme +sphinx-reredirects==0.1.* diff --git a/docs/source/_static/Logo.svg b/docs/source/_static/Logo.svg new file mode 100644 index 00000000..729c06a4 --- /dev/null +++ b/docs/source/_static/Logo.svg @@ -0,0 +1,67 @@ + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 00000000..3d6e35ae --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,19 @@ +.bd-sidebar-primary::-webkit-scrollbar { + width: 8px; + height: 8px; +} + +.bd-sidebar-primary::-webkit-scrollbar-track { + background-color: transparent; + margin-top: 1px; + margin-bottom: 1px; +} + +.bd-sidebar-primary::-webkit-scrollbar-thumb { + border-radius: 9999px; + background-color: rgb(163 163 163); +} + +.bd-sidebar-primary::-webkit-scrollbar-corner { + background-color: transparent; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..5b92fd8f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,24 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = "Autosubmit API" +copyright = "2024, Barcelona Supercomputing Center, BSC" +author = "Earth Sciences Department, Barcelona Supercomputing Center, BSC" + +release = "4.0.0" +version = "4.0.0" + +# -- General configuration + +extensions = [] + +# -- Options for HTML output + +html_theme = "pydata_sphinx_theme" + +html_static_path = ["_static"] + +html_logo = "_static/Logo.svg" + +html_css_files = ["custom.css"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..8ad301e1 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,5 @@ +:html_theme.sidebar_secondary.remove: + +############## +Autosubmit API +############## -- GitLab From e797cf3791693398a77f47961d62cdddcdbf980c Mon Sep 17 00:00:00 2001 From: Luiggi Tenorio Date: Wed, 24 Apr 2024 14:48:48 +0200 Subject: [PATCH 2/3] Include redoc plugin --- docs/source/_static/openapi.json | 972 +++++++++++++++++++++++++++++++ docs/source/conf.py | 14 +- 2 files changed, 985 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/openapi.json diff --git a/docs/source/_static/openapi.json b/docs/source/_static/openapi.json new file mode 100644 index 00000000..d5b24179 --- /dev/null +++ b/docs/source/_static/openapi.json @@ -0,0 +1,972 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "4.0.0", + "title": "Autosubmit API", + "license": { + "url": "https://www.gnu.org/licenses/gpl-3.0.html", + "name": "GNU General Public License" + } + }, + "paths": { + "/v3/running": { + "get": { + "tags": [ + "v3" + ], + "summary": "Running experiments", + "operationId": "get-v3-running", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "experiment": { + "type": "array", + "items": { + "type": "object", + "properties": { + "completed": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "failed": { + "type": "integer" + }, + "hpc": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "modified": { + "type": "string" + }, + "name": { + "type": "string" + }, + "queuing": { + "type": "integer" + }, + "running": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "submitted": { + "type": "integer" + }, + "suspended": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "user": { + "type": "string" + }, + "version": { + "type": "string" + }, + "wrapper": { + "type": "string", + "nullable": true + } + } + } + } + }, + "x-examples": { + "Example 1": { + "experiment": [ + { + "completed": 25, + "description": "Testing AS 4.0", + "failed": 8, + "hpc": "MARENOSTRUM4", + "id": 8192, + "modified": "2022-10-03 10:05:27", + "name": "a4yd", + "queuing": 0, + "running": 0, + "status": "RUNNING", + "submitted": 0, + "suspended": 0, + "total": 385, + "user": "root", + "version": "4.0.0b0", + "wrapper": null + }, + { + "completed": 88, + "description": "TEST_AS_4.0", + "failed": 0, + "hpc": "MARENOSTRUM4", + "id": 8202, + "modified": "2022-11-30 11:50:29", + "name": "t0an", + "queuing": 0, + "running": 0, + "status": "RUNNING", + "submitted": 0, + "suspended": 0, + "total": 91, + "user": "root", + "version": "4.0.0b0", + "wrapper": null + } + ] + } + } + }, + "examples": { + "Example 1": { + "value": { + "experiment": [ + { + "completed": 25, + "description": "Testing AS 4.0", + "failed": 8, + "hpc": "MARENOSTRUM4", + "id": 8192, + "modified": "2022-10-03 10:05:27", + "name": "a4yd", + "queuing": 0, + "running": 0, + "status": "RUNNING", + "submitted": 0, + "suspended": 0, + "total": 385, + "user": "root", + "version": "4.0.0b0", + "wrapper": null + }, + { + "completed": 88, + "description": "TEST_AS_4.0", + "failed": 0, + "hpc": "MARENOSTRUM4", + "id": 8202, + "modified": "2022-11-30 11:50:29", + "name": "t0an", + "queuing": 0, + "running": 0, + "status": "RUNNING", + "submitted": 0, + "suspended": 0, + "total": 91, + "user": "root", + "version": "4.0.0b0", + "wrapper": null + } + ] + } + } + } + } + } + } + } + } + }, + "/v4/experiments": { + "get": { + "tags": [ + "v4" + ], + "summary": "Search experiments", + "description": "", + "operationId": "get-v4-experiments", + "parameters": [ + { + "name": "query", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "only_active", + "in": "query", + "schema": { + "type": "boolean" + } + }, + { + "name": "owner", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "exp_type", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "test", + "operational", + "experiment" + ] + } + }, + { + "name": "autosubmit_version", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "order_by", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "expid", + "created", + "description" + ] + } + }, + { + "name": "order_desc", + "in": "query", + "schema": { + "type": "boolean" + } + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer" + } + }, + { + "name": "page_size", + "in": "query", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "experiments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "completed": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "failed": { + "type": "integer" + }, + "hpc": { + "type": "string", + "nullable": true + }, + "id": { + "type": "integer" + }, + "modified": { + "type": "string", + "nullable": true + }, + "name": { + "type": "string" + }, + "queuing": { + "type": "integer" + }, + "running": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "submitted": { + "type": "integer" + }, + "suspended": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "user": { + "type": "string", + "nullable": true + }, + "version": { + "type": "string" + }, + "wrapper": { + "type": "string", + "nullable": true + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "page": { + "type": "integer" + }, + "page_items": { + "type": "integer" + }, + "page_size": { + "type": "integer" + }, + "total_items": { + "type": "integer" + }, + "total_pages": { + "type": "integer" + } + } + } + }, + "x-examples": { + "Example 1": { + "experiments": [ + { + "completed": 0, + "description": "DE Model App", + "failed": 0, + "hpc": null, + "id": 9, + "modified": null, + "name": "a005", + "queuing": 0, + "running": 0, + "status": "NOT RUNNING", + "submitted": 0, + "suspended": 0, + "total": 0, + "user": null, + "version": "Unknown", + "wrapper": null + }, + { + "completed": 115, + "description": "DE downstream", + "failed": 0, + "hpc": "LOCAL", + "id": 11, + "modified": "2023-10-26 11:44:07", + "name": "a006", + "queuing": 0, + "running": 0, + "status": "NOT RUNNING", + "submitted": 0, + "suspended": 0, + "total": 115, + "user": "ltenorio", + "version": "4.0.95", + "wrapper": null + } + ], + "pagination": { + "page": 1, + "page_items": 2, + "page_size": 2, + "total_items": 9, + "total_pages": 5 + } + } + } + }, + "examples": { + "Example 1": { + "value": { + "experiments": [ + { + "completed": 0, + "description": "DE Model App", + "failed": 0, + "hpc": null, + "id": 9, + "modified": null, + "name": "a005", + "queuing": 0, + "running": 0, + "status": "NOT RUNNING", + "submitted": 0, + "suspended": 0, + "total": 0, + "user": null, + "version": "Unknown", + "wrapper": null + }, + { + "completed": 115, + "description": "DE downstream", + "failed": 0, + "hpc": "LOCAL", + "id": 11, + "modified": "2023-10-26 11:44:07", + "name": "a006", + "queuing": 0, + "running": 0, + "status": "NOT RUNNING", + "submitted": 0, + "suspended": 0, + "total": 115, + "user": "ltenorio", + "version": "4.0.95", + "wrapper": null + } + ], + "pagination": { + "page": 1, + "page_items": 2, + "page_size": 2, + "total_items": 9, + "total_pages": 5 + } + } + } + } + } + } + } + } + } + }, + "/v4/experiments/{expid}": { + "get": { + "tags": [ + "v4" + ], + "summary": "Get experiment info", + "operationId": "get-v4-experiments-expid", + "parameters": [ + { + "name": "expid", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": {} + } + }, + "/v4/experiments/{expid}/jobs": { + "get": { + "tags": [ + "v4" + ], + "summary": "List experiment jobs", + "operationId": "get-v4-experiments-expid-jobs", + "parameters": [ + { + "name": "view", + "in": "query", + "description": "Data view selector", + "schema": { + "type": "string", + "enum": [ + "base", + "quick" + ] + } + }, + { + "name": "expid", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "jobs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Job" + } + } + } + }, + "examples": { + "Example 1": { + "value": { + "jobs": [ + { + "name": "a008_20200120_fc0_2_SIM", + "status": "COMPLETED", + "priority": 4, + "section": "SIM", + "date": "2020-01-20T00:00:00", + "member": "fc0", + "chunk": 2, + "out_path_local": "a008_20200120_fc0_2_SIM.20231027153508.out", + "err_path_local": "a008_20200120_fc0_2_SIM.20231027153508.err", + "out_path_remote": "a008_20200120_fc0_2_SIM.20231027153508.out", + "err_path_remote": "a008_20200120_fc0_2_SIM.20231027153508.err" + } + ] + } + } + } + } + } + } + } + } + }, + "/v4/experiments/{expid}/wrappers": { + "get": { + "tags": [ + "v4" + ], + "summary": "List experiment wrappers", + "operationId": "get-v4-experiments-expid-wrappers", + "parameters": [ + { + "name": "expid", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "wrappers": { + "type": "array", + "items": { + "type": "object", + "properties": { + "job_names": { + "type": "array", + "items": { + "type": "string" + } + }, + "wrapper_name": { + "type": "string" + } + } + } + } + }, + "x-examples": { + "Example 1": { + "wrappers": [ + { + "job_names": [ + "a6zi_18500101_fc0_1_SIM", + "a6zi_18500101_fc0_2_SIM" + ], + "wrapper_name": "a6zi_ASThread_17108563159474_528_10" + }, + { + "job_names": [ + "a6zi_18500101_fc0_3_SIM", + "a6zi_18500101_fc0_4_SIM", + "a6zi_18500101_fc0_5_SIM", + "a6zi_18500101_fc0_6_SIM", + "a6zi_18500101_fc0_7_SIM", + "a6zi_18500101_fc0_8_SIM", + "a6zi_18500101_fc0_9_SIM", + "a6zi_18500101_fc0_10_SIM", + "a6zi_18500101_fc0_11_SIM", + "a6zi_18500101_fc0_12_SIM" + ], + "wrapper_name": "a6zi_ASThread_17108816522924_528_10" + } + ] + } + } + } + } + } + } + } + } + }, + "/v4/auth/verify-token": { + "get": { + "tags": [ + "v4" + ], + "summary": "Verify JWT Token", + "operationId": "get-v4-auth-verify-token", + "parameters": [ + { + "name": "Authorization", + "in": "header", + "description": "JWT Token", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "user": { + "type": "string", + "nullable": true + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": true, + "user": "username" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "user": { + "type": "string", + "nullable": true + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": false, + "user": null + } + } + } + } + } + } + } + } + }, + "/v4/auth/cas/v2/login": { + "get": { + "tags": [ + "v4" + ], + "summary": "CAS v2 Login", + "operationId": "get-v4-auth-cas-v2-login", + "parameters": [ + { + "name": "ticket", + "in": "query", + "description": "CAS ticket", + "schema": { + "type": "string" + } + }, + { + "name": "service", + "in": "query", + "description": "CAS service", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "token": { + "type": "string" + }, + "user": { + "type": "string" + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": true, + "message": "Token generated", + "token": "...", + "user": "username" + } + } + } + } + } + }, + "302": { + "description": "Redirect to CAS login form" + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "token": { + "type": "string", + "nullable": true + }, + "user": { + "type": "string", + "nullable": true + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": false, + "message": "Unauthorized", + "token": null, + "user": null + } + } + } + } + } + } + } + } + }, + "/v4/auth/oauth2/github/login": { + "get": { + "tags": [ + "v4" + ], + "summary": "GitHub Oauth2 App Login", + "operationId": "get-v4-auth-oauth2-github-login", + "parameters": [ + { + "name": "code", + "in": "query", + "description": "GitHub code used to exchange for an access_token", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "token": { + "type": "string" + }, + "user": { + "type": "string" + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": true, + "message": "Token generated", + "token": "...", + "user": "username" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "token": { + "type": "string" + }, + "user": { + "type": "string" + } + } + }, + "examples": { + "Example 1": { + "value": { + "authenticated": false, + "message": "Unauthorized", + "token": null, + "user": null + } + } + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Job": { + "type": "object", + "title": "Job", + "description": "Base experiment job", + "properties": { + "name": { + "type": "string", + "description": "Job identifier" + }, + "status": { + "type": "string", + "enum": [ + "WAITING", + "READY", + "SUBMITTED", + "QUEUING", + "RUNNING", + "COMPLETED", + "HELD", + "PREPARED", + "SKIPPED", + "DELAYED", + "FAILED", + "UNKNOWN", + "SUSPENDED" + ], + "description": "Status of the job", + "default": "UNKNOWN" + }, + "priority": { + "type": "integer" + }, + "section": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date-time" + }, + "member": { + "type": "string" + }, + "chunk": { + "type": "integer" + }, + "out_path_local": { + "type": "string" + }, + "err_path_local": { + "type": "string" + }, + "out_path_remote": { + "type": "string" + }, + "err_path_remote": { + "type": "string" + } + }, + "x-examples": { + "Example 1": { + "name": "a008_20200120_fc0_2_SIM", + "status": "COMPLETED", + "priority": 4, + "section": "SIM", + "date": "2020-01-20T00:00:00", + "member": "fc0", + "chunk": 2, + "out_path_local": "a008_20200120_fc0_2_SIM.20231027153508.out", + "err_path_local": "a008_20200120_fc0_2_SIM.20231027153508.err", + "out_path_remote": "a008_20200120_fc0_2_SIM.20231027153508.out", + "err_path_remote": "a008_20200120_fc0_2_SIM.20231027153508.err" + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 5b92fd8f..1af25c71 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,10 +11,22 @@ version = "4.0.0" # -- General configuration -extensions = [] +extensions = [ + 'sphinxcontrib.redoc' +] # -- Options for HTML output +redoc = [ + { + 'name': 'Autosubmit API', + 'page': 'api', + 'spec': '_static/openapi.json', + # 'spec': 'https://petstore3.swagger.io/api/v3/openapi.json', + # 'spec': 'https://petstore.swagger.io/v2/swagger.json' + } +] + html_theme = "pydata_sphinx_theme" html_static_path = ["_static"] -- GitLab From d7ef565cae29403ca042de6c363bd5b1f575fe48 Mon Sep 17 00:00:00 2001 From: Luiggi Tenorio Date: Wed, 24 Apr 2024 14:49:03 +0200 Subject: [PATCH 3/3] update pages --- docs/source/_static/Logo.svg | 50 ++++++++++++++++++----------- docs/source/configuration/index.rst | 33 +++++++++++++++++++ docs/source/index.rst | 8 +++++ docs/source/installation/index.rst | 23 +++++++++++++ docs/source/usage/index.rst | 31 ++++++++++++++++++ 5 files changed, 127 insertions(+), 18 deletions(-) create mode 100644 docs/source/configuration/index.rst create mode 100644 docs/source/installation/index.rst create mode 100644 docs/source/usage/index.rst diff --git a/docs/source/_static/Logo.svg b/docs/source/_static/Logo.svg index 729c06a4..0777169c 100644 --- a/docs/source/_static/Logo.svg +++ b/docs/source/_static/Logo.svg @@ -11,11 +11,11 @@ height="2.23333in" viewBox="0 0 1200 670" version="1.1" - id="svg3" - sodipodi:docname="as_short.svg" + id="svg1093" + sodipodi:docname="as_api.svg" inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)"> + id="metadata1099"> @@ -26,7 +26,7 @@ + id="defs1097" /> + inkscape:current-layer="svg1093" /> + id="path1914" + style="fill:#4e8490;fill-opacity:1" /> + id="path1912" + style="fill:#4e8490;fill-opacity:1" /> + id="path1910" /> + id="path1906" + style="fill:#ff511c;fill-opacity:1" /> + + + diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst new file mode 100644 index 00000000..79042a9c --- /dev/null +++ b/docs/source/configuration/index.rst @@ -0,0 +1,33 @@ +.. _configuration: + +############## +Configuration +############## + +The Autosubmit API have some configuration options that can be modified by setting their specific environment variable before starting the server: + + +General variables +************************** + +* ``SECRET_KEY``: The secret key to encode the JWT tokens from the Authorization Module. + +.. important:: Always set ``SECRET_KEY`` when deploying the API on production. + + +Authentication variables +************************** + +* ``PROTECTION_LEVEL``: Default ``ALL``. Possible values ``ALL``, ``WRITEONLY``, ``NONE``. + + * If set to ``ALL``, all the endpoints will be protected by needing a valid token inside the **Authorization** header of the request. + * If set to ``WRITEONLY``, only a subset of the endpoints will be protected. + * If set to ``NONE``, none of the endpoints will be protected. + +* ``CAS_SERVER_URL``: CAS Protocol server base URL to request a ticket and verify it. Used for **/v4** endpoints. ``CAS_LOGIN_URL`` and ``CAS_VERIFY_URL`` can be empty if this variable is set (the API will append the protocol URL subpaths). +* ``CAS_LOGIN_URL``: CAS Protocol URL to request a ticket. Used for **/v3** endpoints. +* ``CAS_VERIFY_URL``: CAS Protocol URL to verify a given ticket. Used for **/v3** endpoints. +* ``GITHUB_OAUTH_CLIENT_ID``: Client ID of the Github Oauth app. +* ``GITHUB_OAUTH_CLIENT_SECRET``: Secret key of the Github Oauth app. +* ``GITHUB_OAUTH_WHITELIST_ORGANIZATION``: Used to use authorization based on the membership of a Github organization. +* ``GITHUB_OAUTH_WHITELIST_TEAM``: Used to use authorization based on the membership of a Github team in an organization. ``GITHUB_OAUTH_WHITELIST_ORGANIZATION`` is required \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 8ad301e1..e6ee8166 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,3 +3,11 @@ ############## Autosubmit API ############## + + +.. toctree:: + :maxdepth: 2 + + /installation/index + /configuration/index + /usage/index diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst new file mode 100644 index 00000000..16dcb95e --- /dev/null +++ b/docs/source/installation/index.rst @@ -0,0 +1,23 @@ +.. _installation: + +############## +Installation +############## + +Autosubmit API can be easily installed via pip: + +.. code-block:: bash + + pip install autosubmit-api # >=4.0 (recommended) + + +Then, you can check it's installation and check server options: + +.. code-block:: bash + + autosubmit_api start -h + + +.. note:: See more in Pypi: https://pypi.org/project/autosubmit-api/ + +Continue to :ref:`configuration` or :ref:`usage` once it's installed. \ No newline at end of file diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst new file mode 100644 index 00000000..6c875777 --- /dev/null +++ b/docs/source/usage/index.rst @@ -0,0 +1,31 @@ +.. _usage: + +############## +Usage +############## + +Once Autosubmit API is installed, the Command Line Interface can be used: + +.. code-block:: bash + + autosubmit_api start + +``autosubmit_api start`` will have the following options: + + ``--init-bg-tasks`` + run background tasks on start. + ``--disable-bg-tasks`` + disable background tasks. + ``-b BIND, --`` + bind BIND the socket to bind + ``-w WORKERS, --workers WORKERS`` + the number of worker processes for handling requests + ``--log-level LOG_LEVEL`` + the granularity of Error log outputs + ``--log-file LOG_FILE`` + The Error log file to write to + ``-D, --daemon`` + Daemonize the Gunicorn process + + +You can go to the API reference here: `Reference <../api.html>`_ \ No newline at end of file -- GitLab