Refactor

docs/commands/build.md

@@ -0,0 +1,102 @@
+# Build Commands
+
+This document provides detailed information about the build commands available in fairscape-cli.
+
+## Overview
+
+The `build` command group provides operations for generating derived artifacts from RO-Crates. These artifacts include datasheets, visualizations, and evidence graphs that make the RO-Crate content more accessible and understandable.
+
+```bash
+fairscape-cli build [COMMAND] [OPTIONS]
+```
+
+## Available Commands
+
+- [`datasheet`](#datasheet) - Generate an HTML datasheet for an RO-Crate
+- [`evidence-graph`](#evidence-graph) - Generate a provenance graph for a specific ARK identifier
+
+## Command Details
+
+### `datasheet`
+
+Generate an HTML datasheet for an RO-Crate, providing a human-readable summary of its content.
+
+```bash
+fairscape-cli build datasheet [OPTIONS] ROCRATE_PATH
+```
+
+**Arguments:**
+
+- `ROCRATE_PATH` - Path to the RO-Crate directory or metadata file [required]
+
+**Options:**
+
+- `--output PATH` - Output HTML file path (defaults to ro-crate-datasheet.html in crate directory)
+- `--template-dir PATH` - Custom template directory
+- `--published` - Indicate if the crate is considered published (may affect template rendering)
+
+**Example:**
+
+```bash
+fairscape-cli build datasheet ./my_rocrate
+```
+
+This command:
+
+1. Reads the RO-Crate metadata
+2. Processes any subcrates
+3. Generates a comprehensive HTML datasheet
+4. Saves the datasheet in the specified location (or default location)
+
+The datasheet includes:
+
+- General metadata (title, authors, description)
+- Datasets included in the crate
+- Software included in the crate
+- Computations documented in the crate
+- Provenance relationships between elements
+- References to external resources
+- Information about subcrates (if any)
+
+### `evidence-graph`
+
+Generate a provenance graph for a specific ARK identifier within an RO-Crate.
+
+```bash
+fairscape-cli build evidence-graph [OPTIONS] ROCRATE_PATH ARK_ID
+```
+
+**Arguments:**
+
+- `ROCRATE_PATH` - Path to the RO-Crate directory or metadata file [required]
+- `ARK_ID` - ARK identifier for which to build the evidence graph [required]
+
+**Options:**
+
+- `--output-file PATH` - Path to save the JSON evidence graph (defaults to provenance-graph.json in the RO-Crate directory)
+
+**Example:**
+
+```bash
+fairscape-cli build evidence-graph \
+    ./my_rocrate \
+    ark:59852/dataset-output-dataset-xDNPTmwoHl
+```
+
+This command:
+
+1. Reads the RO-Crate metadata
+2. Identifies all relationships involving the specified ARK identifier
+3. Builds a graph representing the provenance of the entity
+4. Generates both JSON and HTML visualizations of the graph
+5. Updates the RO-Crate metadata to reference the evidence graph
+
+The evidence graph shows:
+
+- Inputs used to create the entity
+- Software used in the computations
+- Computations that generated or used the entity
+- Derived datasets or outputs
+- All relevant metadata for each node in the graph
+
+The HTML visualization provides an interactive graph that can be viewed in a web browser, making it easy to explore the provenance of datasets, software, and computations in the RO-Crate.

docs/commands/import.md

@@ -0,0 +1,100 @@
+# Import Commands
+
+This document provides detailed information about the import commands available in fairscape-cli.
+
+## Overview
+
+The `import` command group provides operations for importing external data into RO-Crate format. These commands fetch data from external repositories and convert them to well-structured RO-Crates with appropriate metadata.
+
+```bash
+fairscape-cli import [COMMAND] [OPTIONS]
+```
+
+## Available Commands
+
+- [`bioproject`](#bioproject) - Import data from an NCBI BioProject
+- [`pep`](#pep) - Import a Portable Encapsulated Project (PEP)
+
+## Command Details
+
+### `bioproject`
+
+Import data from an NCBI BioProject into an RO-Crate.
+
+```bash
+fairscape-cli import bioproject [OPTIONS]
+```
+
+**Options:**
+
+- `--accession TEXT` - NCBI BioProject accession (e.g., PRJNA12345) [required]
+- `--output-dir PATH` - Directory to create the RO-Crate in [required]
+- `--author TEXT` - Author name to associate with generated metadata [required]
+- `--api-key TEXT` - NCBI API key (optional)
+- `--name TEXT` - Override the default RO-Crate name
+- `--description TEXT` - Override the default RO-Crate description
+- `--keywords TEXT` - Override the default RO-Crate keywords (can be used multiple times)
+- `--license TEXT` - Override the default RO-Crate license URL
+- `--version TEXT` - Override the default RO-Crate version
+- `--organization-name TEXT` - Set the organization name for the RO-Crate
+- `--project-name TEXT` - Set the project name for the RO-Crate
+
+**Example:**
+
+```bash
+fairscape-cli import bioproject \
+    --accession "PRJDB2884" \
+    --output-dir "./bioproject_crate" \
+    --author "Jane Smith" \
+    --keywords "genomics" \
+    --keywords "sequencing"
+```
+
+This command:
+
+1. Fetches metadata from the NCBI BioProject database
+2. Creates an RO-Crate with the BioProject metadata
+3. Registers datasets, samples, and other relevant data from the BioProject
+4. Outputs the ARK identifier of the created RO-Crate
+
+### `pep`
+
+Import a Portable Encapsulated Project (PEP) into an RO-Crate.
+
+```bash
+fairscape-cli import pep [OPTIONS] PEP_PATH
+```
+
+**Arguments:**
+
+- `PEP_PATH` - Path to the PEP directory or config file [required]
+
+**Options:**
+
+- `--output-path PATH` - Path for the generated RO-Crate (defaults to PEP directory)
+- `--name TEXT` - Name for the RO-Crate (overrides PEP metadata)
+- `--description TEXT` - Description (overrides PEP metadata)
+- `--author TEXT` - Author (overrides PEP metadata)
+- `--organization-name TEXT` - Organization name
+- `--project-name TEXT` - Project name
+- `--keywords TEXT` - Keywords (overrides PEP metadata, can be used multiple times)
+- `--license TEXT` - License URL (default: "https://creativecommons.org/licenses/by/4.0/")
+- `--date-published TEXT` - Publication date
+- `--version TEXT` - Version string (default: "1.0")
+
+**Example:**
+
+```bash
+fairscape-cli import pep \
+    ./my_pep_project \
+    --output-path ./pep_rocrate \
+    --author "John Doe" \
+    --organization-name "University Example" \
+    --project-name "My PEP Project"
+```
+
+This command:
+
+1. Reads the PEP project configuration
+2. Creates an RO-Crate with metadata from the PEP
+3. Outputs the ARK identifier of the created RO-Crate

docs/commands/publish.md

@@ -0,0 +1,168 @@
+# Publish Commands
+
+This document provides detailed information about the publish commands available in fairscape-cli.
+
+## Overview
+
+The `publish` command group provides operations for publishing RO-Crates to external repositories and registering persistent identifiers. These commands help make your research data FAIR (Findable, Accessible, Interoperable, and Reusable) by connecting it to wider research data ecosystems.
+
+```bash
+fairscape-cli publish [COMMAND] [OPTIONS]
+```
+
+## Available Commands
+
+- [`fairscape`](#fairscape) - Upload RO-Crate directory or zip file to Fairscape
+- [`dataverse`](#dataverse) - Publish RO-Crate metadata as a new dataset to Dataverse
+- [`doi`](#doi) - Mint or update a DOI on DataCite using RO-Crate metadata
+
+## Command Details
+
+### `fairscape`
+
+Upload an RO-Crate directory or zip file to a Fairscape repository.
+
+```bash
+fairscape-cli publish fairscape [OPTIONS]
+```
+
+**Options:**
+
+- `--rocrate PATH` - Path to the RO-Crate directory or zip file [required]
+- `--username TEXT` - Fairscape username (can also be set via FAIRSCAPE_USERNAME env var) [required]
+- `--password TEXT` - Fairscape password (can also be set via FAIRSCAPE_PASSWORD env var) [required]
+- `--api-url TEXT` - Fairscape API URL (default: "https://fairscape.net/api")
+
+**Example:**
+
+```bash
+fairscape-cli publish fairscape \
+    --rocrate ./my_rocrate \
+    --username "your_username" \
+    --password "your_password" \
+    --api-url "https://fairscape.example.org/api"
+```
+
+This command:
+
+1. Authenticates with the Fairscape repository
+2. Uploads the RO-Crate directory or zip file
+3. Registers the metadata in the repository
+4. Returns a URL to access the published RO-Crate
+
+### `dataverse`
+
+Publish RO-Crate metadata as a new dataset to a Dataverse repository.
+
+```bash
+fairscape-cli publish dataverse [OPTIONS]
+```
+
+**Options:**
+
+- `--rocrate PATH` - Path to the ro-crate-metadata.json file [required]
+- `--prefix TEXT` - Your DataCite DOI prefix (e.g., "10.1234") [required]
+- `--username TEXT` - DataCite API username (repository ID, e.g., "MEMBER.REPO") (can use DATACITE_USERNAME env var) [required]
+- `--password TEXT` - DataCite API password (can use DATACITE_PASSWORD env var) [required]
+- `--api-url TEXT` - DataCite API URL (default: "https://api.datacite.org", use "https://api.test.datacite.org" for testing)
+- `--event TEXT` - DOI event type: 'publish' (make public), 'register' (create draft), 'hide' (make findable but hide metadata) [default: "publish"]
+
+**Example:**
+
+```bash
+fairscape-cli publish doi \
+    --rocrate ./my_rocrate/ro-crate-metadata.json \
+    --prefix "10.1234" \
+    --username "MYORG.MYREPO" \
+    --password "your_datacite_password" \
+    --event "publish"
+```
+
+This command:
+
+1. Reads the RO-Crate metadata
+2. Transforms it into DataCite metadata
+3. Mints or updates a DOI on DataCite
+4. Returns the DOI URL
+
+## Working with DOIs
+
+When working with DOIs, keep in mind:
+
+1. **DOI States**:
+
+   - `register`: Creates a draft DOI that is not yet publicly resolvable
+   - `publish`: Makes the DOI and its metadata public and resolvable
+   - `hide`: Makes the DOI resolvable but hides its metadata
+
+2. **Testing**: Use the test DataCite API URL before working with the production system:
+
+   ```bash
+   --api-url "https://api.test.datacite.org"
+   ```
+
+3. **Updating**: To update an existing DOI, ensure the RO-Crate metadata contains the DOI in the `identifier` field.
+
+## Integrating with Dataverse
+
+After minting a DOI, you can update your RO-Crate metadata with the DOI and then publish to Dataverse:
+
+```bash
+# First mint a DOI
+fairscape-cli publish doi --rocrate ./my_rocrate/ro-crate-metadata.json ...
+
+# Then update your RO-Crate with the DOI
+# (This would typically be done programmatically)
+
+# Then publish to Dataverse
+fairscape-cli publish dataverse --rocrate ./my_rocrate/ro-crate-metadata.json ...
+```
+
+This workflow ensures your research data is both persistently identified and accessible through established research data repositories.
+json file [required]
+
+- `--url TEXT` - Base URL of the target Dataverse instance (e.g., "https://dataverse.example.edu") [required]
+- `--collection TEXT` - Alias of the target Dataverse collection to publish into [required]
+- `--token TEXT` - Dataverse API token (can also be set via DATAVERSE_API_TOKEN env var) [required]
+- `--authors-csv PATH` - Optional CSV file with author details (name, affiliation, orcid). Requires "name" column header.
+
+**Example:**
+
+```bash
+fairscape-cli publish dataverse \
+    --rocrate ./my_rocrate/ro-crate-metadata.json \
+    --url "https://dataverse.example.edu" \
+    --collection "my_collection" \
+    --token "your_dataverse_api_token"
+```
+
+This command:
+
+1. Reads the RO-Crate metadata
+2. Transforms it into Dataverse dataset metadata
+3. Creates a new dataset in the specified Dataverse collection
+4. Returns the DOI of the created dataset
+
+### `doi`
+
+Mint or update a DOI on DataCite using RO-Crate metadata.
+
+```bash
+fairscape-cli publish doi [OPTIONS]
+```
+
+**Options:**
+
+- `--rocrate PATH` - Path to the ro-crate-metadata.json file [required]
+- `--prefix TEXT` - Your DataCite DOI prefix (e.g., "10.1234") [required]
+- `--username TEXT` - DataCite API username (repository ID, e.g., "MEMBER.REPO") (can use DATACITE_USERNAME env var) [required]
+- `--password TEXT` - DataCite API password (can use DATACITE_PASSWORD env var) [required]
+- `--api-url TEXT` - DataCite API URL (default: "https://api.datacite.org", use "https://api.test.datacite.org" for testing)
+- `--event TEXT` - DOI event type: 'publish' (make public), 'register' (create draft), 'hide' (make findable but hide metadata) [default: "publish"]
+
+**Example:**
+
+```bash
+fairscape-cli publish doi \
+    --rocrate ./my_rocrate/ro-crate-metadata.
+```