sci-writer 0.1.1
LaTeX manuscript compilation system for scientific documents
Requires Python: >=3.9
Keywords: academic, bibliography, bibtex, compilation, latex, manuscript, paper, scientific-writing

<!-- ---
!-- Timestamp: 2026-01-15
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/sci-writer/README.md
!-- --- -->

# sci-writer

LaTeX manuscript compilation with CLI and MCP server integration.

[![CI](https://github.com/ywatanabe1989/sci-writer/actions/workflows/ci.yml/badge.svg)](https://github.com/ywatanabe1989/sci-writer/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)

<details>
<summary><strong>Installation</strong></summary>

```bash
pip install sci-writer
```

From source:
```bash
git clone https://github.com/ywatanabe1989/sci-writer
cd sci-writer && pip install -e .
```

</details>

<details>
<summary><strong>CLI</strong></summary>

```bash
sci-writer compile ./my-paper              # Compile manuscript
sci-writer compile ./my-paper -t suppl     # Compile supplementary
sci-writer status ./my-paper               # Check dependencies
sci-writer clean ./my-paper                # Remove build artifacts
sci-writer info ./my-paper                 # Project information
```

</details>

<details>
<summary><strong>MCP Server</strong></summary>

Add to Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "sci-writer": {
      "command": "python",
      "args": ["-m", "sci_writer.mcp_server"]
    }
  }
}
```

Available tools:
- `compile` - Compile LaTeX document
- `status` - Check dependencies
- `clean` - Remove build artifacts
- `get_project_info` - Get project structure

</details>

## Quick Start (Shell Scripts)

```bash
git clone https://github.com/ywatanabe1989/sci-writer.git my-paper
cd my-paper
./scripts/shell/compile_manuscript.sh
```

<details>
<summary><strong>Output Structure</strong></summary>

```
my-paper/
├── 00_shared/              # Shared resources (bibliography, styles)
│   ├── bib_files/          # Multiple .bib files (auto-merged)
│   └── latex_styles/       # Common LaTeX configurations
├── 01_manuscript/          # Main manuscript
│   ├── contents/           # Modular content sections
│   │   ├── abstract.tex
│   │   ├── introduction.tex
│   │   ├── methods.tex
│   │   ├── results.tex
│   │   ├── discussion.tex
│   │   ├── figures/        # Figure captions + media
│   │   └── tables/         # Table captions + CSV data
│   ├── archive/            # Version history (auto-generated)
│   ├── manuscript.tex      # Compiled LaTeX
│   └── manuscript.pdf      # Output PDF
├── 02_supplementary/       # Supplementary materials
├── 03_revision/            # Revision response letter
└── scripts/shell/          # Compilation scripts
```

</details>

## Features

| Feature | Description |
|---------|-------------|
| **Multi-Engine** | Auto-selects best engine (Tectonic 1-3s, latexmk 3-6s, 3-pass 12-18s) |
| **Bibliography** | Multi-file with auto-deduplication, 20+ citation styles |
| **Versioning** | Auto-archive, diff generation, git integration |
| **Assets** | Parallel figure/table processing (PNG, PDF, SVG, Mermaid, CSV) |
| **Cross-Platform** | Linux, macOS, WSL2, Docker, Singularity, HPC clusters |

<details>
<summary><strong>Compilation Options</strong></summary>

```bash
# Basic compilation
./scripts/shell/compile_manuscript.sh          # Manuscript
./scripts/shell/compile_supplementary.sh       # Supplementary
./scripts/shell/compile_revision.sh            # Revision letter

# Performance options
./scripts/shell/compile_manuscript.sh --draft      # Fast single-pass
./scripts/shell/compile_manuscript.sh --no-figs    # Skip figures
./scripts/shell/compile_manuscript.sh --no-tables  # Skip tables
./scripts/shell/compile_manuscript.sh --no-diff    # Skip diff generation

# Engine selection
./scripts/shell/compile_manuscript.sh --engine tectonic  # Fastest
./scripts/shell/compile_manuscript.sh --engine latexmk   # Standard
./scripts/shell/compile_manuscript.sh --engine 3pass     # Most compatible

# Development
./scripts/shell/compile_manuscript.sh --watch  # Hot-reload on file changes
./scripts/shell/compile_manuscript.sh --clean  # Remove cache
```

</details>

<details>
<summary><strong>Bibliography Management</strong></summary>

Organize references in multiple `.bib` files - they auto-merge with deduplication:

```bash
00_shared/bib_files/
├── methods_refs.bib      # Method-related references
├── field_background.bib  # Background literature
└── my_papers.bib         # Your own publications
```

Change citation style in `config/config_manuscript.yaml`:
- `unsrtnat` (numbered, order of citation)
- `plainnat` (numbered, alphabetical)
- `apalike` (author-year, APA style)
- `IEEEtran` (IEEE format)
- `naturemag` (Nature style)

</details>

<details>
<summary><strong>Adding Figures</strong></summary>

1. Place media files in `01_manuscript/contents/figures/caption_and_media/`:
   ```
   01_example_figure.png
   01_example_figure.tex  # Caption file
   ```

2. Caption file format (`01_example_figure.tex`):
   ```latex
   %% Figure caption
   \caption{Your figure caption here. Explain panels (A, B, C) if applicable.}
   \label{fig:example_figure_01}
   ```

3. Supported formats: PNG, JPEG, PDF, SVG, TIFF, Mermaid (.mmd)

4. Figures auto-compile and include in `FINAL.tex`

</details>

<details>
<summary><strong>Adding Tables</strong></summary>

1. Place CSV + caption in `01_manuscript/contents/tables/caption_and_media/`:
   ```
   01_example_table.csv
   01_example_table.tex  # Caption file
   ```

2. CSV auto-converts to LaTeX table format

3. Caption file format (`01_example_table.tex`):
   ```latex
   %% Table caption
   \caption{Your table caption. Define abbreviations used.}
   \label{tab:example_table_01}
   ```

</details>

## Installation

<details>
<summary><strong>Ubuntu/Debian</strong></summary>

```bash
sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript
```

</details>

<details>
<summary><strong>macOS</strong></summary>

```bash
brew install texlive latexdiff parallel imagemagick ghostscript
```

</details>

<details>
<summary><strong>HPC / Containers</strong></summary>

```bash
# Module system
module load texlive latexdiff parallel

# Docker
docker run -v $(pwd):/work scitex-writer

# Singularity/Apptainer
singularity run scitex-writer.sif
```

</details>

## Documentation

| Guide | Description |
|-------|-------------|
| [Installation](docs/01_GUIDE_INSTALLATION.md) | Setup for all environments |
| [Quick Start](docs/01_GUIDE_QUICK_START.md) | Common workflows |
| [Content Creation](docs/01_GUIDE_CONTENT_CREATION.md) | Writing manuscripts |
| [Bibliography](docs/01_GUIDE_BIBLIOGRAPHY.md) | Reference management |
| [Architecture](docs/02_ARCHITECTURE_IMPLEMENTATION.md) | Technical details |

---

<p align="center">
  <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
  <br>
  AGPL-3.0 · ywatanabe@scitex.ai
</p>

<!-- EOF -->