📘 Documentation Issue — Create Comprehensive SEPIA Technical & User Documentation (ReadTheDocs Format)

🎯 Goal

Establish a centralized, well-structured SEPIA documentation system that can be published via ReadTheDocs. This documentation should cover both:

• Technical Documentation (architecture, API, models, deployment, developer guide)
• Supportive/User Documentation (usage guides, workflows, examples, screenshots)

The result will serve as the single authoritative reference for all SEPIA components — frontend, backend, and data workflows.

---

🧩 Implementation Details

1. Documentation Platform

• Use Sphinx with the ReadTheDocs theme.
• Structure repository to be compatible with ReadTheDocs build system (docs/ folder).
• Integrate with readthedocs.io for auto-builds from the main branch.

Directory structure example:

docs/
├── conf.py
├── index.rst
├── installation/
│   ├── backend_setup.rst
│   ├── frontend_setup.rst
│   ├── environment_variables.rst
├── api/
│   ├── openapi_overview.rst
│   ├── endpoints/
│   │   ├── sample.rst
│   │   ├── user.rst
│   │   ├── keyword.rst
│   │   ├── etc...
├── development/
│   ├── architecture_overview.rst
│   ├── database_models.rst
│   ├── coding_standards.rst
│   ├── deployment_guide.rst
├── user/
│   ├── intro_to_sepia.rst
│   ├── creating_samples.rst
│   ├── search_samples.rst
│   ├── minting_igsn.rst
│   ├── managing_sample_types.rst
│   ├── faq.rst

---

2. Documentation Content

🧱 Technical Documentation

• Architecture Overview

  • Frontend / Backend separation
  • Database schema & key models (Sample, SampleType, SampleUser, etc.)

• API Reference

  • Auto-generated from OpenAPI specification
  • Each endpoint described with examples and parameters

• Data Flow

  • How data moves between frontend, backend, ICAT, and DataCite

• Deployment & Configuration

  • Installation prerequisites (Python, Node, Postgres, etc.)
  • Environment variable definitions
  • Docker or Compose setup if applicable

• Development Standards

  • Coding style, contribution guide, testing strategy

🙌 User / Support Documentation

• Overview of SEPIA

  • What SEPIA does, high-level features

• Creating and Managing Samples

  • Form walkthrough, file upload options (XML, JSON, CSV…)
  • Dynamic fields based on Sample Type schema

• IGSN Minting

  • How to mint an IGSN and view its landing page

• Searching Samples

  • Filters, keywords, advanced search, etc.

• Managing Users

  • ORCID lookup, ICAT linkage

• FAQ and Troubleshooting

  • Common errors, API responses, and how to resolve them

---

3. Technical Setup

• Initialize with sphinx-quickstart

• Add Sphinx extensions:

  • sphinx_rtd_theme
  • sphinx.ext.autodoc
  • sphinx.ext.napoleon (for Google/NumPy docstrings)
  • sphinx.ext.autosectionlabel
  • sphinx-jsonschema (for documenting JSON schemas)

• Integrate automatic OpenAPI documentation generation (via sphinxcontrib-openapi or recommonmark for Markdown support).

• Configure conf.py to render .rst and .md files.

---

4. Versioning

• Use ReadTheDocs versioning to document:

  • latest (main branch)
  • stable (last release)

• Ensure that backend and frontend version numbers are cross-referenced in documentation headers.

---

5. Deliverables

• Sphinx project initialized and builds locally (make html)
• Hosted on ReadTheDocs with CI build badge
• Covers both technical and user documentation
• Links to API schema and GitLab repos
• Consistent branding (logo, footer, navigation structure)

---

🧪 Testing

• Builds successfully on ReadTheDocs
• Internal links and cross-references resolve correctly
• Example code snippets render properly
• Auto-generated OpenAPI docs integrated
• User guide sections easy to navigate

---

🏷️ Labels

documentation readthedocs feature technical-docs user-docs priority::high