Merge pull request #1149 from sandialabs/update-docs-for-parsing

Update docs for parsing
sandialabs · Jan 24, 2024 · 4c40c6b · 4c40c6b
2 parents 71619a4 + b64a593
commit 4c40c6b
Show file tree

Hide file tree

Showing 43 changed files with 1,441 additions and 123 deletions.
diff --git a/docker/compose/slycat-compose/slycat-docker-compose-authenticated-config.ini b/docker/compose/slycat-compose/slycat-docker-compose-authenticated-config.ini
@@ -25,7 +25,6 @@ projects-redirect: "/projects"
 remote-hosts: [{ "hostnames": ["localhost"], "agent.old": {"command":"/home/slycat/install/conda/bin/python /home/slycat/src/slycat/agent/slycat-docker-agent.py --json /home/slycat/src/slycat/agent/json"}}]
 remote-authentication: {"method":"password", "port":22, "localhost":"sshd"}
 remote-session-timeout: datetime.timedelta(minutes=150)
-server-root: "/"
 show-tracebacks: True
 socket-host: "0.0.0.0"
 socket-port: 8092

diff --git a/docker/compose/slycat-compose/slycat-docker-compose-config.ini b/docker/compose/slycat-compose/slycat-docker-compose-config.ini
@@ -25,7 +25,6 @@ projects-redirect: "/projects"
 remote-hosts: [{ "hostnames": ["localhost", "127.0.0.1"], "agent": {"command":"/home/slycat/install/conda/bin/python /home/slycat/src/slycat/agent/slycat-docker-agent.py --json /home/slycat/src/slycat/agent/json"}}]
 remote-authentication: {"method":"password", "port":22}
 remote-session-timeout: datetime.timedelta(minutes=150)
-server-root: "/"
 show-tracebacks: True
 socket-host: "0.0.0.0"
 socket-port: 8092

diff --git a/docker/slycat-base/web-server-config.ini b/docker/slycat-base/web-server-config.ini
@@ -35,7 +35,6 @@ projects-redirect: "/projects"
 remote-hosts: [{ "hostnames": ["localhost", "127.0.0.1"], "agent": {"command":"/home/slycat/install/conda/bin/python /home/slycat/src/slycat/agent/slycat-docker-agent.py --json /home/slycat/src/slycat/agent/json"}}]
 remote-authentication: {"method":"password", "port":22}
 remote-session-timeout: datetime.timedelta(minutes=150)
-server-root: "/"
 show-tracebacks: True
 socket-host: "127.0.0.1"
 socket-port: 8092

diff --git a/docker/slycat-developer/web-server-config.ini b/docker/slycat-developer/web-server-config.ini
@@ -35,7 +35,6 @@ projects-redirect: "/projects"
 remote-hosts: [{ "hostnames": ["localhost", "127.0.0.1"], "agent": {"command":"/home/slycat/install/conda/bin/python /home/slycat/src/slycat/agent/slycat-docker-agent.py --json /home/slycat/src/slycat/agent/json"}}]
 remote-authentication: {"method":"password", "port":22}
 remote-session-timeout: datetime.timedelta(minutes=150)
-server-root: "/"
 show-tracebacks: True
 socket-host: "127.0.0.1"
 socket-port: 8092

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,84 @@
+# Creating the documentation
+
+# Installing requirements to build the docs
+
+## Python environment
+
+- `conda create --name slycat python==3.11`
+- `pip install sphinx`
+- `pip install sphinx-rtd-theme`
+
+## Install make
+
+### Mac
+
+Option 1:
+
+- `xcode-select --install`
+
+Option 2:
+
+- `brew install make`
+
+## Windows
+
+Option 1, install binary:
+
+- `https://gnuwin32.sourceforge.net/packages/make.htm`
+
+Options 2, install WSL (linux subsystem for windows):
+
+- `https://learn.microsoft.com/en-us/windows/wsl/install`
+
+## Ubuntu
+
+- `sudo apt update`
+- `make -version`
+
+If no version shows up install it with `apt`
+
+- `sudo apt install make`
+
+# Building the docs
+
+From `/docs` in the slycat repo run the following command
+
+- `make html`
+
+This should create a `_build` directory with the resulting sphynx documentation created from the build files.
+
+# Other build options
+
+```bsh
+$ make
+Sphinx v6.1.3
+Please use `make target' where target is one of
+  html        to make standalone HTML files
+  dirhtml     to make HTML files named index.html in directories
+  singlehtml  to make a single large HTML file
+  pickle      to make pickle files
+  json        to make JSON files
+  htmlhelp    to make HTML files and an HTML help project
+  qthelp      to make HTML files and a qthelp project
+  devhelp     to make HTML files and a Devhelp project
+  epub        to make an epub
+  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+  latexpdf    to make LaTeX and PDF files (default pdflatex)
+  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
+  text        to make text files
+  man         to make manual pages
+  texinfo     to make Texinfo files
+  info        to make Texinfo files and run them through makeinfo
+  gettext     to make PO message catalogs
+  changes     to make an overview of all changed/added/deprecated items
+  xml         to make Docutils-native XML files
+  pseudoxml   to make pseudoxml-XML files for display purposes
+  linkcheck   to check all external links for integrity
+  doctest     to run all doctests embedded in the documentation (if enabled)
+  coverage    to run coverage check of the documentation (if enabled)
+  clean       to remove everything in the build directory
+  ```
+
+# Adding the docs to the slycat webserver build
+
+You will need to copy the built docs from `~/docs/_build` to `~/docs/html`
diff --git a/docs/source/DELETE-methods/DELETE-Job.rst b/docs/source/DELETE-methods/DELETE-Job.rst
@@ -0,0 +1,45 @@
+DELETE Job
+==========
+
+.. http:delete:: /api/remotes/delete-job/(hostname)/(jid)
+
+  Deletes a remote job by calling cancel on the job using a connected session to
+  an HPC machine. Submits a command to the slycat-agent to cancel a running job
+  on a cluster running SLURM.
+
+  :param hostname: name of the host where the job is running
+  :type mid: string
+
+  :param jid: Job ID
+  :type mid: string
+
+  :status 204: The remote job has been deleted.
+  :status 400: status message from agent will be displayed
+  :status 500: No Slycat agent present on remote host
+
+  **Sample Request**
+
+  .. sourcecode:: http
+
+    DELETE /api/remotes/hostname/132435 HTTP/1.1
+    Host: localhost:8093
+    Content-Length: 0
+    Authorization: Basic c2x5Y2F0OnNseWNhdA==
+    Accept-Encoding: gzip, deflate, compress
+    Accept: */*
+    User-Agent: python-requests/1.2.3 CPython/2.7.5 Linux/2.6.32-358.23.2.el6.x86_64
+
+  **Sample Response**
+
+  .. sourcecode:: http
+
+    HTTP/1.1 204 Job deleted.
+    Date: Mon, 25 Nov 2013 20:35:59 GMT
+    Content-Type: text/html;charset=utf-8
+    Server: CherryPy/14.0.0
+
+See Also
+--------
+
+- :http:post:`/api/remotes`
+
diff --git a/docs/source/DELETE-methods/DELETE-Model-Parameter.rst b/docs/source/DELETE-methods/DELETE-Model-Parameter.rst
@@ -0,0 +1,51 @@
+DELETE Model Parameter
+======================
+
+.. http:delete:: /api/delete-artifact/(mid)/(aid)
+
+  Deletes an artifact in the model by the Artifact ID (aid)
+
+  :param mid: Unique model identifier.
+  :type mid: string
+
+  :param aid: Unique artifact identifier.
+  :type aid: string
+
+  :status 204: 204 Model deleted.
+
+  **Sample Request**
+
+  .. sourcecode:: http
+
+    DELETE /api/delete-artifact/8b8122539570439cb3703c0f8806158e/aid HTTP/1.1
+    Accept: */*
+    Accept-Encoding: gzip, deflate, br
+    Accept-Language: en-US,en;q=0.9
+    Connection: keep-alive
+    Cookie: slycattimeout=timeout; slycatauth=52230b361ec442ffa6d608da64ab4617
+    DNT: 1
+    Host: localhost:9000
+    Origin: https://localhost:9000
+    Referer: https://localhost:9000/models/a0a6c7d6694b4f99a5b7aa635f3f44a4
+    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.80 Safari/537.36
+    X-Requested-With: XMLHttpRequest
+
+  **Sample Response**
+
+  .. sourcecode:: http
+
+    HTTP/1.1 204 Model deleted.
+    X-Powered-By: Express
+    expires: 0
+    server: CherryPy/14.0.0
+    pragma: no-cache
+    cache-control: no-cache, no-store, must-revalidate
+    date: Thu, 13 Jun 2019 21:33:05 GMT
+    content-type: text/html;charset=utf-8
+    connection: close
+
+See Also
+--------
+
+- :http:delete:`/api/model/(mid)/projects/data/(did)`
+
diff --git a/docs/source/DELETE-methods/DELETE-rest-api.rst b/docs/source/DELETE-methods/DELETE-rest-api.rst
@@ -14,6 +14,8 @@ DELETE METHODS
     DELETE-Project-Data.rst
     DELETE-Project-Data-In-Model.rst
     DELETE-Model-In-Project-Data.rst
+    DELETE-Model-Parameter.rst
     DELETE-reference.rst
     DELETE-Remote.rst
+    DELETE-Job.rst
     DELETE-Upload.rst
diff --git a/docs/source/GET-methods/GET-Configuration-GA-Tracking-ID.rst b/docs/source/GET-methods/GET-Configuration-GA-Tracking-ID.rst
@@ -0,0 +1,41 @@
+GET Configuration GA Tracking ID
+================================
+
+.. http:get:: /api/configuration/ga-tracking-id
+
+  Returns the Google Analytics tracking ID if one exists
+
+  :status 200:
+
+  :responseheader Content-Type: application/json
+
+  **Sample Request**
+
+  .. sourcecode:: http
+
+    GET /api/configuration/ga-tracking-id HTTP/1.1
+    Host: localhost:9000
+    Connection: keep-alive
+    Accept: application/json, text/javascript, */*; q=0.01
+    X-Requested-With: XMLHttpRequest
+    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.80 Safari/537.36
+    Referer: https://localhost:9000/models/b26d9a5d7b2f44729bffccad51fdfcf9?bid=405d84f7553f53736beabdf874d55356
+    Accept-Encoding: gzip, deflate, br
+    Accept-Language: en-US,en;q=0.9
+    Cookie: slycatauth=e9528234ede94e159fc21ef2f744323f; slycattimeout=timeout
+
+  **Sample Response**
+
+  .. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    X-Powered-By: Express
+    content-type: application/json;charset=utf-8
+    content-length: 43
+    expires: 0
+    server: CherryPy/18.8.0
+    pragma: no-cache
+    cache-control: no-cache, no-store, must-revalidate
+    date: Fri, 20 Oct 2023 15:55:35 GMT
+    connection: close
+
diff --git a/docs/source/GET-methods/GET-Configuration-Markings.rst b/docs/source/GET-methods/GET-Configuration-Markings.rst
@@ -0,0 +1,54 @@
+GET Configuration Markings
+==========================
+
+.. http:get:: /api/configuration/markings
+
+  Retrieves the markings as a JSON array of marking objects. An example response is presented in this document.
+
+  :responseheader Content-Type: application/json
+
+  **Sample Request**
+
+  .. sourcecode:: http
+
+    GET /api/configuration/markings HTTP/1.1
+    Host: localhost:9000
+    Connection: keep-alive
+    Accept: application/json, text/javascript, */*; q=0.01
+    DNT: 1
+    X-Requested-With: XMLHttpRequest
+    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.80 Safari/537.36
+    Referer: https://localhost:9000/models/b26d9a5d7b2f44729bffccad51fdfcf9?bid=405d84f7553f53736beabdf874d55356
+    Accept-Encoding: gzip, deflate, br
+    Accept-Language: en-US,en;q=0.9
+    Cookie: slycatauth=e9528234ede94e159fc21ef2f744323f; slycattimeout=timeout
+
+  **Sample Response**
+
+  .. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    X-Powered-By: Express
+    content-length: 43
+    expires: 0
+    server: CherryPy/14.0.0
+    pragma: no-cache
+    cache-control: no-cache, no-store, must-revalidate
+    date: Fri, 14 Jun 2019 19:41:58 GMT
+    content-type: application/json
+    connection: close
+
+    [
+      {
+        "label": "None",
+        "badge": "",
+        "page-before": null,
+        "page-after": null,
+        "type": "mna"
+      }
+    ]
+
+See Also
+--------
+
+- :http:get:`/api/configuration/selectable-markings`
diff --git a/docs/source/GET-methods/GET-Configuration-Parsers.rst b/docs/source/GET-methods/GET-Configuration-Parsers.rst
@@ -0,0 +1,57 @@
+GET Configuration Parsers
+=========================
+
+.. http:get:: /api/configuration/parsers
+
+  Returns a list of parser objects and their metadata. These are the parsers that are available from the Slycat server
+  for parsing uploaded data, such as CSVs, into the Slycat server for displaying models. You can generally find parsers
+  displayed in the Slycat model wizards.
+
+  :status 200:
+
+  :responseheader Content-Type: application/json
+
+  **Sample Request**
+
+  .. sourcecode:: http
+
+    GET /api/configuration/parsers HTTP/1.1
+    Host: localhost:9000
+    Connection: keep-alive
+    Accept: application/json, text/javascript, */*; q=0.01
+    X-Requested-With: XMLHttpRequest
+    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.80 Safari/537.36
+    Referer: https://localhost:9000/models/b26d9a5d7b2f44729bffccad51fdfcf9?bid=405d84f7553f53736beabdf874d55356
+    Accept-Encoding: gzip, deflate, br
+    Accept-Language: en-US,en;q=0.9
+    Cookie: slycatauth=e9528234ede94e159fc21ef2f744323f; slycattimeout=timeout
+
+  **Sample Response**
+
+  .. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    X-Powered-By: Express
+    content-type: application/json;charset=utf-8
+    content-length: 43
+    expires: 0
+    server: CherryPy/18.8.0
+    pragma: no-cache
+    cache-control: no-cache, no-store, must-revalidate
+    date: Fri, 20 Oct 2023 15:55:35 GMT
+    connection: close
+
+    [
+      {
+          "type": "slycat-csv-parser",
+          "label": "Comma separated values (CSV)",
+          "categories": [
+              "table"
+          ]
+      }
+    ]
+
+See Also
+--------
+
+- :http:get:`/api/projects`