Merge pull request #12 from kbase/doc-fix

Trying to repair GitHub pages deployment.

.github/workflows/gh-pages.yml

@@ -42,18 +42,19 @@ jobs:
       - name: Build
         run: uv run --dev mkdocs build --verbose
 
-      - if: ${{ github.event_name == 'push' }}
+      - if: ${{ github.event_name == 'push' }} || ${{ github.event_name == 'workflow_dispatch' }}
         name: GitHub Pages action
-        uses: JamesIves/github-pages-deploy-action@v4
+        uses: JamesIves/github-pages-deploy-action@v4.6.8
         with:
           # Do not remove existing pr-preview pages
           clean-exclude: pr-preview
           folder: ./site/
+          force: false # don't force-push, which overwrites previews
 
       # If it's a PR from within the same repo, deploy to a preview page
       # For security reasons, PRs from forks cannot write into gh-pages for now
       - if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
         name: Preview docs
-        uses: rossjrw/pr-preview-action@v1
+        uses: rossjrw/pr-preview-action@v1.4.8
         with:
           source-dir: ./site/

docs/index.md

@@ -1,2 +1,67 @@
-# dtspy: a Python client for the [Data Transfer System](https://kbase.github.io/dts/)
+# dtspy: a Python client for the Data Transfer System (DTS)
 
+The `dtspy` Python client allows you to use the [DTS](https://kbase.github.io/dts/)
+to search for files and transfer them between several organizations supported
+by the Department of Energy (DOE) Biological and Environmental Research (BER)
+program:
+
+* [JGI Data Portal (JDP)](https://data.jgi.doe.gov/)
+* [DOE National Microbiome Data Collaborative (NMDC)](https://microbiomedata.org/)
+* [DOE Biology Knowledgebase(KBase)](https://www.kbase.us)
+* More coming soon!
+
+You can use `dtspy` to create a client that connects to a DTS server, and use
+that client to
+
+* search for data files within databases supported by the above organizations,
+  obtaining their canonical IDs and metadata identifying their provenance
+* request the transfer of one or more of these data files between databases by
+  using canonical file IDs
+
+## Prerequisites for Using `dtspy`
+
+To use the DTS Python client, you need
+
+* Python 3.12
+* an [ORCID account](https://orcid.org/register)
+* a [KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account) with a
+  [developer token](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials)
+
+DTS uses KBase's authentication server, so the token associates your DTS client
+with your KBase account, allowing you to transfer files to it.
+
+## Installation
+
+We recommend installing `dtspy` in a [virtual environment](https://docs.python.org/3/library/venv.html)
+alongside any tools or workflows you use to analyze the data you're working with.
+You can install `dtspy` using `pip` (or `pip3`):
+
+```
+pip install dtspy
+```
+
+## Quickstart
+
+Below is an example describing how to create a DTS client connected to a server,
+search for files within the JGI Data Portal, and print their metadata.
+
+
+```py
+import dts
+import os
+
+# to avoid putting your developer token in your Python scripts, store it
+# in an environment variable like `DTS_KBASE_DEV_TOKEN`
+token = os.getenv('DTS_KBASE_DEV_TOKEN')
+
+# connect to the DTS server
+dts_client = dts.Client(api_key = token,
+                        server = "https://lb-dts.staging.kbase.us")
+
+# search the JGI Data Portal for files related to prochlorococcus, a small
+# marine cyanobacteria
+files = dts_client.search(database = 'jdp',
+                          query = 'prochlorococcus')
+print(files)
+
+```