diff --git a/docs/.gitkeep b/docs/.gitkeep deleted file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..0ba74d9de564abbe8af7fe09cec0235660f5d999 --- /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 0000000000000000000000000000000000000000..5deaf0fcd539a53568bbb3fb0b143af9c5c8556a --- /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 0000000000000000000000000000000000000000..0777169c215fc0a8c6ed43f2146a756835247cfd --- /dev/null +++ b/docs/source/_static/Logo.svg @@ -0,0 +1,81 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000000000000000000000000000000000000..3d6e35ae27b5c21d9a4b9365ee3387cba8b8708c --- /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/_static/openapi.json b/docs/source/_static/openapi.json new file mode 100644 index 0000000000000000000000000000000000000000..d5b24179325fc518a550325b286d3860813e05a3 --- /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 new file mode 100644 index 0000000000000000000000000000000000000000..1af25c71cb3198d165a3593b3f06d1085a168e82 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,36 @@ +# 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 = [ + '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"] + +html_logo = "_static/Logo.svg" + +html_css_files = ["custom.css"] diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..79042a9c2bdd977b537555c6b9f6323d7f058a7a --- /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 new file mode 100644 index 0000000000000000000000000000000000000000..e6ee8166f4939248008ba7bca875b9fa870ff8b8 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,13 @@ +:html_theme.sidebar_secondary.remove: + +############## +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 0000000000000000000000000000000000000000..16dcb95e2364ea8be397f4b147a2295c76ae91b3 --- /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 0000000000000000000000000000000000000000..6c875777567834df06dd1b0d423c1b2c2c9c11f7 --- /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