docs: browsable API reference on GitHub Pages

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Building and publishing documentation
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install requirements
+        run: |
+          pip install -r requirements.txt
+          pip install -r tests/requirements.txt
+
+      - name: Install app
+        run: pip install .
+
+      - name: Create markdown documents
+        run: |
+          lazydocs \
+              --output-path="./docs/docstrings" \
+              --overview-file="README.md" \
+              --src-base-url="https://github.com/ohsu-comp-bio/py-tes/blob/master/"
+              --validate \
+              "./tes"
+
+      - name: Build docs
+        run: mkdocs build

.github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: py-test_file
+name: Linting and testing
 
 on: [pull_request]
 

.gitignore

@@ -19,6 +19,7 @@ eggs/
 # Misc
 test_tmp
 *venv*
+docs/docstrings
 
 # Created by https://www.toptal.com/developers/gitignore/api/python
 # Edit at https://www.toptal.com/developers/gitignore?templates=python

README.md

@@ -42,112 +42,7 @@ cli.cancel_task(task_id)
 tasks_list = cli.list_tasks(view="MINIMAL")  # default view
 ```
 
-### How to...
+### Documentation
 
-> Makes use of the objects above...
-
-#### ...export a model to a dictionary
-
-```python
-task_dict = task.as_dict(drop_empty=False)
-```
-
-`task_dict` contents:
-
-```console
-{'id': None, 'state': None, 'name': None, 'description': None, 'inputs': None, 'outputs': None, 'resources': None, 'executors': [{'image': 'alpine', 'command': ['echo', 'hello'], 'workdir': None, 'stdin': None, 'stdout': None, 'stderr': None, 'env': None}], 'volumes': None, 'tags': None, 'logs': None, 'creation_time': None}
-```
-
-#### ...export a model to JSON
-
-```python
-task_json = task.as_json()  # also accepts `drop_empty` arg
-```
-
-`task_json` contents:
-
-```console
-{"executors": [{"image": "alpine", "command": ["echo", "hello"]}]}
-```
-
-#### ...pretty print a model
-
-```python
-print(task.as_json(indent=3))  # keyword args are passed to `json.dumps()`
-```
-
-Output:
-
-```json
-{
-   "executors": [
-      {
-         "image": "alpine",
-         "command": [
-            "echo",
-            "hello"
-         ]
-      }
-   ]
-}
-```
-
-#### ...access a specific task from the task list
-
-```python
-specific_task = tasks_list.tasks[5]
-```
-
-`specific_task` contents:
-
-```console
-Task(id='393K43', state='COMPLETE', name=None, description=None, inputs=None, outputs=None, resources=None, executors=None, volumes=None, tags=None, logs=None, creation_time=None)
-```
-
-#### ...iterate over task list items
-
-```python
-for t in tasks_list[:3]:
-    print(t.as_json(indent=3))
-```
-
-Output:
-
-```console
-{
-   "id": "task_A2GFS4",
-   "state": "RUNNING"
-}
-{
-   "id": "task_O8G1PZ",
-   "state": "CANCELED"
-}
-{
-   "id": "task_W246I6",
-   "state": "COMPLETE"
-}
-```
-
-#### ...instantiate a model from a JSON representation
-
-```python
-task_from_json = tes.client.unmarshal(task_json, tes.Task)
-```
-
-`task_from_json` contents:
-
-```console
-Task(id=None, state=None, name=None, description=None, inputs=None, outputs=None, resources=None, executors=[Executor(image='alpine', command=['echo', 'hello'], workdir=None, stdin=None, stdout=None, stderr=None, env=None)], volumes=None, tags=None, logs=None, creation_time=None)
-```
-
-Which is equivalent to `task`:
-
-```python
-print(task_from_json == task)
-```
-
-Output:
-
-```console
-True
-```
+For additional details, recipes and an API reference, read the
+[docs](https://ohsu-comp-bio.github.io/py-tes).

docs/.pages

@@ -0,0 +1,3 @@
+nav:
+    - Overview: README.md
+    - ...

docs/README.md

@@ -0,0 +1,149 @@
+py-tes
+======
+
+_py-tes_ is a library for interacting with servers implementing the [GA4GH Task Execution Schema](https://github.com/ga4gh/task-execution-schemas).
+
+
+### Install
+
+Available on [PyPI](https://pypi.org/project/py-tes/).
+
+```
+pip install py-tes
+```
+
+### Example
+
+```python
+import tes
+
+# define task
+task = tes.Task(
+    executors=[
+        tes.Executor(
+            image="alpine",
+            command=["echo", "hello"]
+        )
+    ]
+)
+
+# create client
+cli = tes.HTTPClient("https://funnel.example.com", timeout=5)
+
+# access endpoints
+service_info = cli.get_service_info()
+task_id = cli.create_task(task)
+task_info = cli.get_task(task_id, view="BASIC")
+cli.cancel_task(task_id)
+tasks_list = cli.list_tasks(view="MINIMAL")  # default view
+```
+
+### How to...
+
+> Makes use of the objects above...
+
+#### ...export a model to a dictionary
+
+```python
+task_dict = task.as_dict(drop_empty=False)
+```
+
+`task_dict` contents:
+
+```console
+{'id': None, 'state': None, 'name': None, 'description': None, 'inputs': None, 'outputs': None, 'resources': None, 'executors': [{'image': 'alpine', 'command': ['echo', 'hello'], 'workdir': None, 'stdin': None, 'stdout': None, 'stderr': None, 'env': None}], 'volumes': None, 'tags': None, 'logs': None, 'creation_time': None}
+```
+
+#### ...export a model to JSON
+
+```python
+task_json = task.as_json()  # also accepts `drop_empty` arg
+```
+
+`task_json` contents:
+
+```console
+{"executors": [{"image": "alpine", "command": ["echo", "hello"]}]}
+```
+
+#### ...pretty print a model
+
+```python
+print(task.as_json(indent=3))  # keyword args are passed to `json.dumps()`
+```
+
+Output:
+
+```json
+{
+   "executors": [
+      {
+         "image": "alpine",
+         "command": [
+            "echo",
+            "hello"
+         ]
+      }
+   ]
+}
+```
+
+#### ...access a specific task from the task list
+
+```python
+specific_task = tasks_list.tasks[5]
+```
+
+`specific_task` contents:
+
+```console
+Task(id='393K43', state='COMPLETE', name=None, description=None, inputs=None, outputs=None, resources=None, executors=None, volumes=None, tags=None, logs=None, creation_time=None)
+```
+
+#### ...iterate over task list items
+
+```python
+for t in tasks_list[:3]:
+    print(t.as_json(indent=3))
+```
+
+Output:
+
+```console
+{
+   "id": "task_A2GFS4",
+   "state": "RUNNING"
+}
+{
+   "id": "task_O8G1PZ",
+   "state": "CANCELED"
+}
+{
+   "id": "task_W246I6",
+   "state": "COMPLETE"
+}
+```
+
+#### ...instantiate a model from a JSON representation
+
+```python
+task_from_json = tes.client.unmarshal(task_json, tes.Task)
+```
+
+`task_from_json` contents:
+
+```console
+Task(id=None, state=None, name=None, description=None, inputs=None, outputs=None, resources=None, executors=[Executor(image='alpine', command=['echo', 'hello'], workdir=None, stdin=None, stdout=None, stderr=None, env=None)], volumes=None, tags=None, logs=None, creation_time=None)
+```
+
+Which is equivalent to `task`:
+
+```python
+print(task_from_json == task)
+```
+
+Output:
+
+```console
+True
+```

docs/docstring/.pages

@@ -0,0 +1,4 @@
+title: API Reference
+nav:
+    - Overview: README.md
+    - ...

docs/docstring/README.md

@@ -0,0 +1,48 @@
+<!-- markdownlint-disable -->
+
+# API Overview
+
+## Modules
+
+- [`client`](./client.md#module-client): TES access methods and helper functions.
+- [`models`](./models.md#module-models): TES models, converters, validators and helpers.
+- [`utils`](./utils.md#module-utils): Exceptions and utilities.
+
+## Classes
+
+- [`client.HTTPClient`](./client.md#class-httpclient): HTTP client class for interacting with the TES API.
+- [`models.Base`](./models.md#class-base): `attrs` base class for all TES and helper models.
+- [`models.CancelTaskRequest`](./models.md#class-canceltaskrequest): `attrs` model class for `POST /tasks/{id}:cancel` request parameters.
+- [`models.CancelTaskResponse`](./models.md#class-canceltaskresponse): TES `tesCancelTaskResponse` `attrs` model class.
+- [`models.CreateTaskResponse`](./models.md#class-createtaskresponse): TES `tesCreateTaskResponse` `attrs` model class.
+- [`models.Executor`](./models.md#class-executor): TES `tesExecutor` `attrs` model class.
+- [`models.ExecutorLog`](./models.md#class-executorlog): TES `tesExecutorLog` `attrs` model class.
+- [`models.GetTaskRequest`](./models.md#class-gettaskrequest): `attrs` model class for `GET /tasks/{id}` request parameters.
+- [`models.Input`](./models.md#class-input): TES `tesInput` `attrs` model class.
+- [`models.ListTasksRequest`](./models.md#class-listtasksrequest): `attrs` model class for `GET /tasks` request parameters.
+- [`models.ListTasksResponse`](./models.md#class-listtasksresponse): TES `tesListTasksResponse` `attrs` model class.
+- [`models.Output`](./models.md#class-output): TES `tesOutput` `attrs` model class.
+- [`models.OutputFileLog`](./models.md#class-outputfilelog): TES `tesOutputFileLog` `attrs` model class.
+- [`models.Resources`](./models.md#class-resources): TES `tesResources` `attrs` model class.
+- [`models.ServiceInfo`](./models.md#class-serviceinfo): TES `tesServiceInfo` `attrs` model class.
+- [`models.ServiceInfoRequest`](./models.md#class-serviceinforequest): `attrs` model class for `GET /service-info` request parameters.
+- [`models.Task`](./models.md#class-task): TES `tesTask` `attrs` model class.
+- [`models.TaskLog`](./models.md#class-tasklog): TES `tesTaskLog` `attrs` model class.
+- [`utils.TimeoutError`](./utils.md#class-timeouterror)
+- [`utils.UnmarshalError`](./utils.md#class-unmarshalerror): Raised when a JSON string cannot be unmarshalled to a TES model.
+
+## Functions
+
+- [`client.process_url`](./client.md#function-process_url)
+- [`models.datetime_json_handler`](./models.md#function-datetime_json_handler): JSON handler for `datetime` objects.
+- [`models.int64conv`](./models.md#function-int64conv): Convert string to `int64`.
+- [`models.list_of`](./models.md#function-list_of): `attrs` validator for lists of a given type.
+- [`models.strconv`](./models.md#function-strconv): Explicitly cast a string-like value or list thereof to string(s).
+- [`models.timestampconv`](./models.md#function-timestampconv): Convert string to `datetime`.
+- [`utils.camel_to_snake`](./utils.md#function-camel_to_snake): Converts camelCase to snake_case.
+- [`utils.unmarshal`](./utils.md#function-unmarshal): Unmarshal a JSON string to a TES model.
+
+
+---
+
+_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._