Update documentation template

Author: kks32

.github/workflows/build-test.yml

@@ -11,8 +11,8 @@ jobs:
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Run image

.github/workflows/docs.yml

@@ -1,13 +1,9 @@
-name: Deploy MkDocs
+name: deploy-book
 
 on:
   push:
     branches:
       - main
-      - dev
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
   workflow_dispatch:
 
 permissions:
@@ -20,51 +16,37 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  build:
+  deploy-book:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+      - uses: actions/checkout@v4
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.x'
-
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
-
-      - name: Load cached venv
-        id: cached-poetry-dependencies
-        uses: actions/cache@v4
-        with:
-          path: .venv
-          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+          python-version: "3.12"
 
       - name: Install dependencies
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root
+        run: |
+          pip install jupyter-book
+          pip install .
 
-      - name: Build MkDocs site
-        run: poetry run mkdocs build
+      - name: Build the book
+        run: |
+          jupyter-book build . --path-output out
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./site
+          path: ./out/_build/html
 
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: deploy-book
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.github/workflows/pypi.yml

@@ -14,8 +14,8 @@ jobs:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
       contents: read   # Required for checkout
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.9
       - name: Poetry image

.gitignore

@@ -140,7 +140,10 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# Jupyter Book build output
+/out/
+
+# mkdocs documentation (legacy)
 /site
 
 # mypy

_config.yml

@@ -0,0 +1,48 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: DAPI - DesignSafe API
+author: Krishna Kumar, Pedro Arduino, Scott Brandenberg
+logo: docs/nheri.png
+copyright: "2024"
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+exclude_patterns:
+  - _build
+  - out
+  - "**.ipynb_checkpoints"
+  - examples
+  - README.md
+  - AUTHORS.md
+  - LICENSE.md
+  - mkdocs.yml
+
+execute:
+  execute_notebooks: "off"
+
+launch_buttons:
+  notebook_interface: "jupyterlab"
+  colab_url: "https://colab.research.google.com"
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/DesignSafe-CI/dapi
+  branch: main
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+  extra_navbar: ""
+
+sphinx:
+  extra_extensions:
+    - sphinx.ext.autodoc
+    - sphinx.ext.napoleon
+    - sphinx.ext.viewcode
+  config:
+    napoleon_google_docstring: true
+    napoleon_numpy_docstring: true
+    autodoc_member_order: "bysource"

_toc.yml

@@ -0,0 +1,34 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: docs/index
+parts:
+  - caption: Getting Started
+    chapters:
+      - file: docs/installation
+      - file: docs/authentication
+      - file: docs/quickstart
+  - caption: User Guide
+    chapters:
+      - file: docs/jobs
+      - file: docs/database
+  - caption: Examples
+    chapters:
+      - file: docs/examples
+      - file: docs/examples/apps
+      - file: docs/examples/mpm
+      - file: docs/examples/opensees
+      - file: docs/examples/openfoam
+      - file: docs/examples/database
+  - caption: API Reference
+    chapters:
+      - file: docs/api/index
+      - file: docs/api/client
+      - file: docs/api/jobs
+      - file: docs/api/files
+      - file: docs/api/apps
+      - file: docs/api/systems
+      - file: docs/api/database
+      - file: docs/api/auth
+      - file: docs/api/exceptions

docs/api/apps.md

@@ -4,8 +4,12 @@ Application discovery and management for DesignSafe computational applications.
 
 ## Application Discovery
 
-::: dapi.apps.find_apps
+```{eval-rst}
+.. autofunction:: dapi.apps.find_apps
+```
 
 ## Application Details
 
-::: dapi.apps.get_app_details
+```{eval-rst}
+.. autofunction:: dapi.apps.get_app_details
+```

docs/api/auth.md

@@ -4,4 +4,6 @@ Authentication and credential management for DesignSafe access.
 
 ## Authentication
 
-::: dapi.auth.init
+```{eval-rst}
+.. autofunction:: dapi.auth.init
+```

docs/api/client.md

@@ -2,7 +2,12 @@
 
 The main client interface for all DAPI functionality. DSClient provides organized access to DesignSafe resources through the Tapis V3 API.
 
-::: dapi.client.DSClient
+```{eval-rst}
+.. autoclass:: dapi.client.DSClient
+ :members:
+ :undoc-members:
+ :show-inheritance:
+```
 
 ## Accessing the Raw Tapis Client
 
@@ -26,30 +31,47 @@ jobs = tapis_client.jobs.getJobList()
 ### When to Use the Raw Tapis Client
 
 - Access Tapis APIs not yet wrapped by dapi
-- Use advanced search parameters not exposed by dapi  
+- Use advanced search parameters not exposed by dapi 
 - Implement custom functionality
 - Debug or troubleshoot API calls
 - Access experimental or new Tapis features
 
-!!! warning
-    When using the raw Tapis client, you'll need to handle errors and data formatting yourself. The dapi wrapper provides error handling and user-friendly formatting.
+:::{warning}
+When using the raw Tapis client, you'll need to handle errors and data formatting yourself. The dapi wrapper provides error handling and user-friendly formatting.
+:::
 
 ## Service Interfaces
 
 The DSClient provides access to different DesignSafe services through specialized interface classes:
 
 ### AppMethods
 
-::: dapi.client.AppMethods
+```{eval-rst}
+.. autoclass:: dapi.client.AppMethods
+ :members:
+ :undoc-members:
+```
 
 ### FileMethods
 
-::: dapi.client.FileMethods
+```{eval-rst}
+.. autoclass:: dapi.client.FileMethods
+ :members:
+ :undoc-members:
+```
 
 ### JobMethods
 
-::: dapi.client.JobMethods
+```{eval-rst}
+.. autoclass:: dapi.client.JobMethods
+ :members:
+ :undoc-members:
+```
 
 ### SystemMethods
 
-::: dapi.client.SystemMethods
+```{eval-rst}
+.. autoclass:: dapi.client.SystemMethods
+ :members:
+ :undoc-members:
+```

docs/api/database.md

@@ -4,12 +4,24 @@ Database connections and query execution for DesignSafe research databases.
 
 ## Database Accessor
 
-::: dapi.db.accessor.DatabaseAccessor
+```{eval-rst}
+.. autoclass:: dapi.db.accessor.DatabaseAccessor
+ :members:
+ :undoc-members:
+ :show-inheritance:
+```
 
 ## Database Engine
 
-::: dapi.db.db.DSDatabase
+```{eval-rst}
+.. autoclass:: dapi.db.db.DSDatabase
+ :members:
+ :undoc-members:
+ :show-inheritance:
+```
 
 ## Database Configuration
 
-::: dapi.db.config.db_config
+```{eval-rst}
+.. autodata:: dapi.db.config.db_config
+```