Add comprehensive Sphinx-compatible documentation (#117)

* Add comprehensive Sphinx-compatible documentation

- Add NumPy-style docstrings to all main modules:
  - maap.py: Core MAAP client class with all methods documented
  - Result.py: Result, Granule, and Collection classes
  - dps_job.py: DPSJob class for job management
  - Profile.py: User profile management
  - AWS.py: AWS credential management
  - Secrets.py: User secrets management
  - config_reader.py: Configuration management

- Create Sphinx documentation structure:
  - docs/conf.py: Sphinx configuration with Napoleon for NumPy docstrings
  - docs/index.rst: Main documentation index
  - docs/api/*.rst: API reference pages for all modules

- Update package __init__.py with module-level documentation

Documentation follows NumPy docstring format compatible with Sphinx
autodoc and napoleon extensions for API documentation generation.

* Fix algorithm registration docs to use correct inputs structure

Update registerAlgorithm and register_algorithm_from_yaml_file
docstrings to use the correct 'inputs' structure with 'file',
'config', and 'positional' arrays instead of the deprecated
'algorithm_params' format.

Addresses PR review comments from grallewellyn.

* Add GitHub Actions workflow and convert docs to Markdown

- Add .github/workflows/docs.yml for automated doc building and
  deployment to GitHub Pages
- Convert all .rst documentation files to Markdown format
- Add MyST parser to Sphinx configuration for Markdown support
- Add docs/requirements.txt with sphinx, sphinx-rtd-theme, myst-parser
- Add docs/Makefile for local doc builds

Addresses PR feedback from wildintellect requesting GitHub Actions
workflow and Markdown format instead of reStructuredText.

* algorithm_params to inputs in last spot

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: grallewellyn <[email protected]>

Author: 3 people

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Build Documentation
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install -e .
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/Makefile

@@ -0,0 +1,18 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/aws.md

@@ -0,0 +1,36 @@
+# AWS Credentials
+
+```{eval-rst}
+.. automodule:: maap.AWS
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: maap.AWS.AWS
+   :members:
+   :special-members: __init__
+```
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# Get requester-pays credentials
+creds = maap.aws.requester_pays_credentials()
+print(f"Access Key: {creds['accessKeyId']}")
+
+# Generate a signed URL
+signed = maap.aws.s3_signed_url('bucket', 'path/to/file.h5')
+print(f"Signed URL: {signed['url']}")
+
+# Get Earthdata DAAC credentials
+daac_creds = maap.aws.earthdata_s3_credentials(
+    'https://data.lpdaac.earthdatacloud.nasa.gov/s3credentials'
+)
+
+# Get workspace bucket credentials
+workspace_creds = maap.aws.workspace_bucket_credentials()
+```

docs/api/config.md

@@ -0,0 +1,42 @@
+# Configuration
+
+```{eval-rst}
+.. automodule:: maap.config_reader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: maap.config_reader.MaapConfig
+   :members:
+   :special-members: __init__
+```
+
+## Environment Variables
+
+The following environment variables can be used to configure the MAAP client:
+
+| Variable | Description |
+|----------|-------------|
+| `MAAP_API_HOST` | Override the default MAAP API hostname |
+| `MAAP_API_HOST_SCHEME` | URL scheme (http/https) for API connections |
+| `MAAP_CMR_PAGE_SIZE` | Number of results per page for CMR queries |
+| `MAAP_CMR_CONTENT_TYPE` | Content type for CMR requests |
+| `MAAP_PGT` | Proxy granting ticket for authentication |
+| `MAAP_AWS_ACCESS_KEY_ID` | AWS access key for S3 operations |
+| `MAAP_AWS_SECRET_ACCESS_KEY` | AWS secret key for S3 operations |
+| `MAAP_S3_USER_UPLOAD_BUCKET` | S3 bucket for user file uploads |
+| `MAAP_S3_USER_UPLOAD_DIR` | S3 directory for user file uploads |
+| `MAAP_MAPBOX_ACCESS_TOKEN` | Mapbox token for visualization |
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# Access configuration
+print(f"API Root: {maap.config.maap_api_root}")
+print(f"Page Size: {maap.config.page_size}")
+print(f"Granule Search URL: {maap.config.search_granule_url}")
+```

docs/api/dps.md

@@ -0,0 +1,57 @@
+# DPS (Data Processing System)
+
+The DPS module provides classes for submitting and managing processing jobs.
+
+## DPSJob
+
+```{eval-rst}
+.. automodule:: maap.dps.dps_job
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: maap.dps.dps_job.DPSJob
+   :members:
+   :special-members: __init__
+```
+
+## DpsHelper
+
+```{eval-rst}
+.. automodule:: maap.dps.DpsHelper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# Submit a job
+job = maap.submitJob(
+    identifier='my_analysis',
+    algo_id='my_algorithm',
+    version='main',
+    queue='maap-dps-worker-8gb',
+    input_file='s3://bucket/input.tif'
+)
+
+# Check status
+print(f"Job ID: {job.id}")
+print(f"Status: {job.status}")
+
+# Wait for completion
+job.wait_for_completion()
+
+# Get results
+if job.status == 'Succeeded':
+    print(f"Outputs: {job.outputs}")
+    print(f"Duration: {job.job_duration_seconds}s")
+
+# Cancel a job
+job.cancel_job()
+```

docs/api/maap.md

@@ -0,0 +1,34 @@
+# MAAP Client
+
+```{eval-rst}
+.. automodule:: maap.maap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+```
+
+The {class}`~maap.maap.MAAP` class is the main entry point for all MAAP operations.
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+# Initialize
+maap = MAAP()
+
+# Search granules
+granules = maap.searchGranule(short_name='GEDI02_A', limit=10)
+
+# Search collections
+collections = maap.searchCollection(provider='MAAP')
+
+# Submit a job
+job = maap.submitJob(
+    identifier='analysis',
+    algo_id='my_algo',
+    version='main',
+    queue='maap-dps-worker-8gb'
+)
+```

docs/api/profile.md

@@ -0,0 +1,26 @@
+# User Profile
+
+```{eval-rst}
+.. automodule:: maap.Profile
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: maap.Profile.Profile
+   :members:
+   :special-members: __init__
+```
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# Get user account information
+info = maap.profile.account_info()
+if info:
+    print(f"User ID: {info['id']}")
+    print(f"Username: {info['username']}")
+```

docs/api/result.md

@@ -0,0 +1,64 @@
+# Result Classes
+
+```{eval-rst}
+.. automodule:: maap.Result
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+The Result module provides classes for handling CMR search results.
+
+## Classes
+
+### Result
+
+Base class for CMR results.
+
+```{eval-rst}
+.. autoclass:: maap.Result.Result
+   :members:
+   :special-members: __init__
+```
+
+### Granule
+
+Represents a CMR granule (individual data file).
+
+```{eval-rst}
+.. autoclass:: maap.Result.Granule
+   :members:
+   :special-members: __init__
+```
+
+### Collection
+
+Represents a CMR collection (dataset).
+
+```{eval-rst}
+.. autoclass:: maap.Result.Collection
+   :members:
+   :special-members: __init__
+```
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# Search granules
+granules = maap.searchGranule(short_name='GEDI02_A', limit=5)
+
+for granule in granules:
+    # Get URLs
+    s3_url = granule.getS3Url()
+    http_url = granule.getHttpUrl()
+
+    # Download
+    local_path = granule.getData(destpath='/tmp')
+
+    # Get description
+    print(granule.getDescription())
+```

docs/api/secrets.md

@@ -0,0 +1,35 @@
+# User Secrets
+
+```{eval-rst}
+.. automodule:: maap.Secrets
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: maap.Secrets.Secrets
+   :members:
+   :special-members: __init__
+```
+
+## Example Usage
+
+```python
+from maap.maap import MAAP
+
+maap = MAAP()
+
+# List all secrets
+secrets_list = maap.secrets.get_secrets()
+for secret in secrets_list:
+    print(f"Secret: {secret['secret_name']}")
+
+# Get a specific secret
+value = maap.secrets.get_secret('my_api_key')
+print(f"Value: {value}")
+
+# Add a new secret
+maap.secrets.add_secret('my_new_key', 'my_secret_value')
+
+# Delete a secret
+maap.secrets.delete_secret('my_old_key')
+```