Version 2 update

[douglowe]

This pull request introduces comprehensive documentation for the RO-Crate Validation Service, including user and contributor guides, an API reference, and a dedicated page for Five Safes RO-Crate validation. It also adds a GitHub Actions workflow to automate documentation site deployment. These changes significantly improve the discoverability, usability, and maintainability of the service by providing clear instructions for usage, contribution, and integration.

Documentation additions:

• Added an overview and introduction to the service, including descriptions of validation methods and links to further documentation in docs/index.md.
• Added a detailed API reference (docs/api.md) covering endpoint usage, request/response formats, error codes, webhook behavior, and object store integration.
• Added a contributor and development guide (docs/contribution.md) with instructions for setting up a development environment, running tests, linting, CI workflows, and project structure.
• Added a dedicated page for validating Five Safes RO-Crates, including usage instructions, example runs, and integration notes in docs/five-safes.md.

Automation:

• Introduced a GitHub Actions workflow (.github/workflows/deploy_docs.yml) to automatically build and deploy the documentation site on pushes to main or via manual dispatch.

[Copilot]

🟡 Changes recommended

The docs deployment workflow can be manually dispatched from non-main branches and potentially overwrite the GitHub Pages site, and there are a few documentation/PR-scope fixes to address.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a MkDocs-based documentation site for the RO-Crate Validation Service (user + contributor guides and an API reference), plus a GitHub Actions workflow to build and deploy the docs to GitHub Pages. It also includes an update to the pinned dependency lockfiles.

Changes:

• Added new MkDocs site configuration and multiple documentation pages (installation, upgrading, API reference, Five Safes guide, contribution guide).
• Added a GitHub Actions workflow to build and deploy the documentation site to GitHub Pages.
• Updated pinned dependency versions in requirements.txt and requirements-dev.txt.

File summaries

File	Description
requirements.txt	Refreshes runtime lockfile dependency pins.
requirements-dev.txt	Refreshes dev/test lockfile dependency pins.
mkdocs.yml	Adds MkDocs site configuration (nav/theme/plugins).
docs/index.md	Adds docs landing page and conceptual overview.
docs/installation.md	Adds installation/setup guide and configuration reference.
docs/upgrading.md	Adds upgrade notes for 1.x → 2.x (S3 settings + API changes).
docs/api.md	Adds API reference with endpoints, status codes, and result formats.
docs/five-safes.md	Adds Five Safes profile usage guide and examples.
docs/contribution.md	Adds contributor/development guide (stack, tests, lint, CI, structure).
.github/workflows/deploy_docs.yml	Adds Pages build/deploy workflow for MkDocs site.

Review details

Suppressed comments (1)

docs/installation.md:58

• In this context these are standard “environment variables” (not “environmental variables”).

    The service does not create the bucket itself. Create the bucket in the console or with an S3 client. The bucket name needs to match the value in the `S3_BUCKET` environmental variable (`ro-crates` by default). 

• Files reviewed: 9/10 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.