added mkdocs

Author: TejasMorbagal

docs/about.md

@@ -0,0 +1,30 @@
+# About
+
+## Changelog
+See `CHANGES.md`.
+
+## Reporting issues
+Open an issue at https://github.com/deepesdl/deep-code/issues.
+
+## Contributions
+PRs are welcome. Please follow the code style (black/ruff) and add tests where relevant.
+
+## Development install
+```bash
+pip install -e .[dev]
+pytest
+pytest --cov=deep-code
+black .
+ruff check .
+```
+
+## Documentation commands (MkDocs)
+```bash
+pip install -e .[docs]      # install mkdocs + theme
+mkdocs serve                # live preview at http://127.0.0.1:8000
+mkdocs build                # build site into site/
+mkdocs gh-deploy --clean    # publish to GitHub Pages
+```
+
+## License
+MIT License. See `LICENSE`.

docs/cli.md

@@ -0,0 +1,30 @@
+# CLI
+
+## Generate configs
+Create starter templates for both workflow and dataset:
+
+```bash
+deep-code generate-config                 # writes to current directory
+deep-code generate-config -o ./configs    # custom output folder
+```
+
+## Publish metadata
+Publish dataset, workflow, or both (default is both) to the target environment:
+
+```bash
+deep-code publish dataset.yaml workflow.yaml                 # production (default)
+deep-code publish dataset.yaml workflow.yaml -e staging      # staging
+deep-code publish dataset.yaml -m dataset                    # dataset only
+deep-code publish workflow.yaml -m workflow                  # workflow only
+deep-code publish --dataset-config ./ds.yaml --workflow-config ./wf.yaml -m all
+```
+
+Options:
+- `--environment/-e`: `production` (default) | `staging` | `testing`
+- `--mode/-m`: `all` (default) | `dataset` | `workflow`
+- `--dataset-config` / `--workflow-config`: explicitly set paths and bypass auto-detection
+
+## How publishing works
+1. Reads your configs and builds dataset STAC collections plus variable catalogs.
+2. Builds workflow and experiment OGC API Records.
+3. Forks/clones the target metadata repo (production, staging, or testing), commits generated JSON, and opens a pull request on your behalf.

docs/configuration.md

@@ -0,0 +1,37 @@
+# Configuration
+
+## Dataset config (YAML)
+```yaml
+dataset_id: your-dataset.zarr
+collection_id: your-collection
+osc_themes: [cryosphere]
+osc_region: global
+dataset_status: completed   # or ongoing/planned
+documentation_link: https://example.com/docs
+access_link: s3://bucket/your-dataset.zarr
+```
+
+## Workflow config (YAML)
+```yaml
+workflow_id: your-workflow
+properties:
+  title: "My workflow"
+  description: "What this workflow does"
+  keywords: ["Earth Science"]
+  themes: ["cryosphere"]
+  license: proprietary
+  jupyter_kernel_info:
+    name: deepesdl-xcube-1.8.3
+    python_version: 3.11
+    env_file: https://example.com/environment.yml
+jupyter_notebook_url: https://github.com/org/repo/path/to/notebook.ipynb
+contact:
+  - name: Jane Doe
+    organization: Example Org
+    links:
+      - rel: about
+        type: text/html
+        href: https://example.org
+```
+
+More templates and examples live in `dataset_config.yaml`, `workflow_config.yaml`, and `example-config/`.

docs/examples.md

@@ -0,0 +1,5 @@
+# Examples
+
+- Templates: `dataset_config.yaml`, `workflow_config.yaml`
+- Example configs: `examples/example-config/`
+- Notebooks on publishing: `examples/notebooks` 

docs/getting-started.md

@@ -0,0 +1,43 @@
+# Getting Started
+
+When working with cloud platforms like DeepESDL, workflow outputs typically live in S3 object storage. Before the project ends or once datasets and workflows are finalized, move the datasets into the ESA Project Results Repository (PRR) and publish the workflows (Jupyter notebooks) to a publicly accessible GitHub repository. The notebook path becomes an input in the dataset config file.
+
+Use the EarthCODE Project Results Repository to publish and preserve outputs from ESA-funded Earth observation projects. It is professionally maintained, FAIR-aligned, and keeps your results findable, reusable, and citable for the long term—no storage, operations, or access headaches.
+
+To transfer datasets into the ESA PRR, contact the DeepESDL platform team at [[email protected]](mailto:[email protected]).
+
+In the near future, `deep-code` will include built-in support for uploading your results to the ESA PRR as part of the publishing workflow, making it seamless to share your scientific contributions with the community.
+
+## Requirements
+- Python 3.10+
+- GitHub token with access to the target EarthCODE metadata repo.
+- Input configuration files.
+- Datasets which needs to be published is uploaded to S3 like object storage and made publicly accessible.
+
+## Install
+```bash
+pip install deep-code
+```
+
+## Authentication
+The CLI or the Python API reads GitHub credentials from a `.gitaccess` file in the directory where you run the command:
+
+1. **Generate a GitHub Personal Access Token (PAT)**
+
+    1. Navigate to GitHub → Settings → Developer settings → Personal access tokens.
+    2. Click “Generate new token”.
+    3. Choose the following scopes to ensure full access:
+        - repo (Full control of repositories — includes fork, pull, push, and read)
+    4. Generate the token and copy it immediately — GitHub won’t show it again.
+
+2. **Create the .gitaccess File**
+
+    Create a plain text file named .gitaccess in your project directory or home folder:
+
+    ```
+    github-username: your-git-user
+    github-token: your-personal-access-token
+    ```
+    Replace your-git-user and your-personal-access-token with your actual GitHub username and token.
+
+

docs/index.md

@@ -0,0 +1,39 @@
+# Overview
+
+`deep-code` is a lightweight Python CLI and API that publishes DeepESDL datasets and workflows as EarthCODE Open Science Catalog metadata. It can generate starter configs, build STAC collections and OGC API records, and open pull requests to the target EarthCODE metadata repository (production, staging, or testing).
+
+## Features
+- Generate starter dataset and workflow YAML templates.
+- Publish dataset collections, workflows, and experiments via a single command.
+- Build STAC collections and catalogs for Datasets and their corresponding variables automatically from the dataset metadata.
+- Build OGC API records for Workflows and Experiments from your configs.
+- Flexible publishling targets i.e production/staging/testing EarthCODE metadata repositories with GitHub automation.
+
+```mermaid
+%%{init: {'flowchart': {'nodeSpacing': 110, 'rankSpacing': 160}, 'themeVariables': {'fontSize': '28px', 'lineHeight': '1.6em'}}}%%
+flowchart LR
+    subgraph User
+        A["Config files<br/>(dataset.yaml, workflow.yaml)"]
+        B["deep-code CLI<br/>(generate-config, publish)"]
+    end
+
+    subgraph App["deep-code internals"]
+        C["Publisher<br/>(mode: dataset/workflow/all)"]
+        D["STAC builder<br/>OscDatasetStacGenerator"]
+        E["OGC record builder<br/>OSCWorkflowOGCApiRecordGenerator"]
+        F["GitHubAutomation<br/>(fork, clone, branch, PR)"]
+    end
+
+    subgraph Output
+        G["Generated JSON<br/>collections, variables,<br/>workflows, experiments"]
+        H["GitHub PR<br/>(prod/staging/testing repo)"]
+        I["EarthCODE Open Science Catalog"]
+    end
+
+    A --> B --> C
+    C --> D
+    C --> E
+    D --> G
+    E --> G
+    G --> F --> H --> I
+```

docs/python-api.md

@@ -0,0 +1,23 @@
+# Python API
+
+`deep_code.tools.publish.Publisher` is the main entry point.
+
+```python
+from deep_code.tools.publish import Publisher
+
+publisher = Publisher(
+    dataset_config_path="dataset.yaml",
+    workflow_config_path="workflow.yaml",
+    environment="staging",
+)
+
+# Generate files locally (no PR)
+publisher.publish(write_to_file=True, mode="all")
+
+# Or open a PR directly
+publisher.publish(write_to_file=False, mode="dataset")
+```
+
+Other utilities:
+- `deep_code.tools.new.TemplateGenerator` for programmatic template generation.
+- `deep_code.utils.dataset_stac_generator.OscDatasetStacGenerator` and `deep_code.utils.ogc_record_generator.OSCWorkflowOGCApiRecordGenerator` for lower-level metadata building.