#!/usr/bin/env python3
# Timestamp: "2026-02-17 (ywatanabe)"
# File: /home/ywatanabe/proj/scitex-python/src/scitex/template/_project/_generate_readme.py
"""Generate README.md files for new projects.
All functions accept a plain metadata dict — no Django dependencies.
"""
from pathlib import Path
from typing import Dict
__all__ = ["create_minimal_readme", "create_project_readme"]
[docs]
def create_minimal_readme(project_dir: str, metadata: Dict) -> Path:
"""Create a minimal README for empty projects.
Parameters
----------
project_dir : str
Project root directory.
metadata : dict
Keys: ``name``, ``created_at``, ``owner_full_name`` or ``owner``,
``description``.
Returns
-------
Path
Path to the generated README.md.
"""
name = metadata.get("name", "Untitled")
created = str(metadata.get("created_at", ""))
owner = metadata.get("owner_full_name") or metadata.get("owner", "")
description = metadata.get("description") or "No description provided."
content = f"""# {name}
**Created:** {created}
**Owner:** {owner}
## Description
{description}
## Getting Started
This is an empty project directory. You can:
1. **Create from template** - Set up a full SciTeX research project structure
2. **Upload your files** - Upload existing project files
3. **Create manually** - Organize your project structure as you prefer
---
*Created with SciTeX Cloud*
"""
out = Path(project_dir) / "README.md"
out.write_text(content, encoding="utf-8")
return out
[docs]
def create_project_readme(project_dir: str, metadata: Dict) -> Path:
"""Create a comprehensive README for templated projects.
Parameters
----------
project_dir : str
Project root directory.
metadata : dict
Keys: ``name``, ``created_at``, ``updated_at``,
``owner_full_name`` or ``owner``, ``description``,
``hypotheses``, ``progress``, ``id``.
Returns
-------
Path
Path to the generated README.md.
"""
name = metadata.get("name", "Untitled")
created = str(metadata.get("created_at", ""))
updated = str(metadata.get("updated_at", created))
owner = metadata.get("owner_full_name") or metadata.get("owner", "")
description = metadata.get("description") or "No description provided."
hypotheses = metadata.get("hypotheses") or "No hypotheses defined."
progress = metadata.get("progress", 0)
proj_id = metadata.get("id", "")
content = f"""# {name}
**Created:** {created}
**Owner:** {owner}
**Progress:** {progress}%
## Description
{description}
## Hypotheses
{hypotheses}
## Directory Structure
This project follows the standardized SciTeX research project structure:
- `config/` - Configuration files (YAML, JSON, etc.)
- `data/` - Research data (raw, processed, figures, models)
- `scripts/` - Source code and analysis scripts
- `docs/` - Documentation (manuscripts, notes, references)
- `results/` - Analysis outputs (outputs, reports, analysis)
- `temp/` - Temporary files (cache, logs, tmp)
## Getting Started
This project directory is managed by SciTeX Cloud. You can:
1. Upload files using the web interface
2. Edit documents in the Writer module
3. Run code in the Code module
4. Create visualizations in the Viz module
5. Manage references in the Scholar module
## Project Management
- Project ID: {proj_id}
- Created: {created}
- Last Updated: {updated}
---
*This README was automatically generated by SciTeX Cloud*
"""
out = Path(project_dir) / "README.md"
out.write_text(content, encoding="utf-8")
return out
# EOF