docs: rewrite README (#51)

Author: DiogoRibeiro7

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Documentation Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install Poetry
+        run: pip install poetry
+      - name: Install dependencies
+        run: poetry install --with docs
+      - name: Build documentation
+        run: poetry run sphinx-build -W -b html docs/source docs/build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: docs/build/

.readthedocs.yml

@@ -4,10 +4,22 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+    post_install:
+      - poetry config virtualenvs.create false
+      - poetry install --with docs
 
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
 
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: false
+
+formats:
+  - pdf
+  - epub

README.md

@@ -1,180 +1,97 @@
 # gen_surv
 
-![Coverage](https://codecov.io/gh/DiogoRibeiro7/genSurvPy/branch/main/graph/badge.svg)
-[![Docs](https://readthedocs.org/projects/gensurvpy/badge/?version=stable)](https://gensurvpy.readthedocs.io/en/stable/)
-![PyPI](https://img.shields.io/pypi/v/gen_surv)
-![Tests](https://github.com/DiogoRibeiro7/genSurvPy/actions/workflows/test.yml/badge.svg)
-![Python](https://img.shields.io/pypi/pyversions/gen_surv)
+[![Coverage](https://codecov.io/gh/DiogoRibeiro7/genSurvPy/branch/main/graph/badge.svg)](https://app.codecov.io/gh/DiogoRibeiro7/genSurvPy)
+[![Docs](https://readthedocs.org/projects/gensurvpy/badge/?version=latest)](https://gensurvpy.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/gen_surv)](https://pypi.org/project/gen-surv/)
+[![Tests](https://github.com/DiogoRibeiro7/genSurvPy/actions/workflows/test.yml/badge.svg)](https://github.com/DiogoRibeiro7/genSurvPy/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/gen_surv)](https://pypi.org/project/gen-surv/)
 
-
-**gen_surv** is a Python package for simulating survival data under a variety of models, inspired by the R package [`genSurv`](https://cran.r-project.org/package=genSurv). It supports data generation for:
-
-- Cox Proportional Hazards Models (CPHM)
-- Continuous-Time Markov Models (CMM)
-- Time-Dependent Covariate Models (TDCM)
-- Time-Homogeneous Hidden Markov Models (THMM)
+**gen_surv** is a Python package for simulating survival data under a variety of statistical models. It is inspired by the R package [genSurv](https://cran.r-project.org/package=genSurv) and provides a unified interface for generating realistic survival datasets.
 
 ---
 
-## 📦 Installation
+## Features
 
-```bash
-poetry install
-```
-This package requires **Python 3.10** or later.
-## ✨ Features
-
-- Consistent interface across models
-- Censoring support (`uniform` or `exponential`)
-- Easy integration with `pandas` and `NumPy`
-- Suitable for benchmarking survival algorithms and teaching
-- Accelerated Failure Time (Log-Normal) model generator
+- Cox proportional hazards model (CPHM)
+- Accelerated failure time models (log-normal, log-logistic)
+- Continuous-time multi-state Markov model (CMM)
+- Time-dependent covariate model (TDCM)
+- Time-homogeneous hidden Markov model (THMM)
 - Mixture cure and piecewise exponential models
 - Competing risks generators (constant and Weibull hazards)
-- Command-line interface powered by `Typer`
-- Export utilities for CSV, JSON, and Feather formats
+- Command-line interface and export utilities
 
-## 🧪 Example
+## Installation
 
-```python
-from gen_surv import generate
+Install the latest release from PyPI:
 
-# CPHM
-generate(model="cphm", n=100, model_cens="uniform", cens_par=1.0, beta=0.5, covariate_range=2.0)
-
-# AFT Log-Normal
-generate(model="aft_ln", n=100, beta=[0.5, -0.3], sigma=1.0, model_cens="exponential", cens_par=3.0)
-
-# CMM
-generate(model="cmm", n=100, model_cens="exponential", cens_par=2.0,
-         qmat=[[0, 0.1], [0.05, 0]], p0=[1.0, 0.0])
-
-# TDCM
-generate(model="tdcm", n=100, dist="weibull", corr=0.5,
-         dist_par=[1, 2, 1, 2], model_cens="uniform", cens_par=1.0,
-         beta=[0.1, 0.2, 0.3], lam=1.0)
-
-# THMM
-generate(model="thmm", n=100, qmat=[[0, 0.2, 0], [0.1, 0, 0.1], [0, 0.3, 0]],
-         emission_pars={"mu": [0.0, 1.0, 2.0], "sigma": [0.5, 0.5, 0.5]},
-         p0=[1.0, 0.0, 0.0], model_cens="exponential", cens_par=3.0)
-
-# Mixture Cure
-generate(model="mixture_cure", n=100, cure_fraction=0.3, seed=42)
-
-# Piecewise Exponential
-generate(
-    model="piecewise_exponential",
-    n=100,
-    breakpoints=[1.0, 3.0],
-    hazard_rates=[0.2, 0.5, 1.0],
-    seed=0
-)
+```bash
+pip install gen-surv
 ```
 
-## ⌨️ Command-Line Usage
-
-Install the package and use ``python -m gen_surv`` to generate datasets without
-writing Python code:
+To develop locally with all extras:
 
 ```bash
-python -m gen_surv dataset aft_ln --n 100 > data.csv
+git clone https://github.com/DiogoRibeiro7/genSurvPy.git
+cd genSurvPy
+poetry install
 ```
 
-## 🔧 API Overview
-
-| Function | Description |
-|----------|-------------|
-| `generate()` | Unified interface that calls any generator |
-| `gen_cphm()` | Cox Proportional Hazards Model |
-| `gen_cmm()`  | Continuous-Time Multi-State Markov Model |
-| `gen_tdcm()` | Time-Dependent Covariate Model |
-| `gen_thmm()` | Time-Homogeneous Markov Model |
-| `gen_aft_log_normal()` | Accelerated Failure Time Log-Normal |
-| `gen_aft_log_logistic()` | AFT model with log-logistic baseline |
-| `gen_competing_risks()` | Competing risks with constant hazards |
-| `gen_competing_risks_weibull()` | Competing risks with Weibull hazards |
-| `gen_mixture_cure()` | Mixture cure model |
-| `cure_fraction_estimate()` | Estimate cure fraction |
-| `gen_piecewise_exponential()` | Piecewise exponential model |
-| `sample_bivariate_distribution()` | Sample correlated Weibull or exponential times |
-| `runifcens()` | Generate uniform censoring times |
-| `rexpocens()` | Generate exponential censoring times |
-| `export_dataset()` | Save a dataset to CSV, JSON or Feather |
-
-
-```text
-genSurvPy/
-├── gen_surv/             # Pacote principal
-│   ├── __main__.py       # Interface CLI via python -m
-│   ├── cphm.py
-│   ├── cmm.py
-│   ├── tdcm.py
-│   ├── thmm.py
-│   ├── censoring.py
-│   ├── bivariate.py
-│   ├── validate.py
-│   └── interface.py
-├── tests/                # Testes automatizados
-│   ├── test_cphm.py
-│   ├── test_cmm.py
-│   ├── test_tdcm.py
-│   ├── test_thmm.py
-├── examples/             # Exemplos de uso
-│   ├── run_aft.py
-│   ├── run_cmm.py
-│   ├── run_cphm.py
-│   ├── run_tdcm.py
-│   └── run_thmm.py
-├── docs/                 # Documentação Sphinx
-│   ├── source/
-│   └── ...
-├── scripts/              # Utilidades diversas
-│   └── check_version_match.py
-├── tasks.py              # Tarefas automatizadas com Invoke
-├── TODO.md               # Roadmap de desenvolvimento
-├── pyproject.toml        # Configurado com Poetry
-├── README.md
-├── LICENCE
-└── .gitignore
-```
+## Quick Example
 
-## 🧠 License
+```python
+from gen_surv import generate
 
-MIT License. See [LICENCE](LICENCE) for details.
+# basic Cox proportional hazards data
+sim = generate(model="cphm", n=100, beta=0.5, covar=2.0,
+               model_cens="uniform", cens_par=1.0)
+```
 
+See the [usage guide](docs/source/getting_started.md) for more examples.
 
-## 🔖 Release Process
+## Supported Models
 
-This project uses Git tags to manage releases. A GitHub Actions workflow
-(`version-check.yml`) verifies that the version declared in `pyproject.toml`
-matches the latest Git tag. If they diverge, the workflow fails and prompts a
-correction before merging. Run `python scripts/check_version_match.py` locally
-before creating a tag to catch issues early.
+| Model                | Description                             |
+|----------------------|-----------------------------------------|
+| **CPHM**             | Cox proportional hazards                |
+| **AFT**              | Accelerated failure time (log-normal, log-logistic) |
+| **CMM**              | Continuous-time multi-state Markov      |
+| **TDCM**             | Time-dependent covariates                |
+| **THMM**             | Time-homogeneous hidden Markov          |
+| **Competing Risks**  | Multiple event types with cause-specific hazards |
+| **Mixture Cure**     | Models long-term survivors              |
+| **Piecewise Exponential** | Flexible baseline hazard via intervals |
 
-## 🌟 Code of Conduct
+More details on each algorithm are available in the [Algorithms](docs/source/algorithms.md) page and the [theory guide](docs/source/theory.md).
 
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) to learn about the
-expectations for participants in this project.
+## Command-Line Usage
 
-## 🤝 Contributing
+Datasets can be generated without writing Python code:
+
+```bash
+python -m gen_surv dataset cphm --n 1000 -o survival.csv
+```
 
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up your environment, running tests, and submitting pull requests.
+## Documentation
 
-## 🔧 Development Tasks
+Full documentation is hosted on [Read the Docs](https://gensurvpy.readthedocs.io/en/latest/). It includes installation instructions, tutorials, API references and a bibliography.
 
-Common project commands are defined in [`tasks.py`](tasks.py) and can be executed with [Invoke](https://www.pyinvoke.org/):
+To build the docs locally:
 
 ```bash
-poetry run inv -l  # list available tasks
-poetry run inv test  # run the test suite
+cd docs
+make html
 ```
 
-## 📑 Citation
+Open `build/html/index.html` in your browser to view the result.
+
+## License
+
+This project is licensed under the MIT License. See [LICENCE](LICENCE) for details.
 
-If you use **gen_surv** in your work, please cite it using the metadata in
-[`CITATION.cff`](CITATION.cff). Many reference managers can import this file
-directly.
+## Citation
+
+If you use **gen_surv** in your research, please cite the project using the metadata in [CITATION.cff](CITATION.cff).
 
 ## Author
 
@@ -183,3 +100,4 @@ directly.
 - ORCID: <https://orcid.org/0009-0001-2022-7072>
 - Professional email: <[email protected]>
 - Personal email: <[email protected]>
+

docs/requirements.txt

@@ -1,2 +1,6 @@
-sphinx
-myst-parser
+sphinx>=6.0
+myst-parser>=1.0.0,<4.0.0
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+sphinx-copybutton
+sphinx-design

docs/source/_static/custom.css

@@ -0,0 +1,56 @@
+/* Custom styling for gen_surv documentation */
+
+/* Improve code block appearance */
+.highlight {
+    background: #f8f9fa;
+    border: 1px solid #e9ecef;
+    border-radius: 4px;
+    padding: 10px;
+    margin: 10px 0;
+}
+
+/* Style admonitions */
+.admonition {
+    border-radius: 6px;
+    margin: 1em 0;
+    padding: 1em;
+}
+
+.admonition.tip {
+    border-left: 4px solid #28a745;
+    background-color: #d4edda;
+}
+
+.admonition.note {
+    border-left: 4px solid #007bff;
+    background-color: #cce5ff;
+}
+
+.admonition.warning {
+    border-left: 4px solid #ffc107;
+    background-color: #fff3cd;
+}
+
+/* Table styling */
+table.docutils {
+    border-collapse: collapse;
+    margin: 1em 0;
+    width: 100%;
+}
+
+table.docutils th,
+table.docutils td {
+    border: 1px solid #ddd;
+    padding: 8px;
+    text-align: left;
+}
+
+table.docutils th {
+    background-color: #f8f9fa;
+    font-weight: bold;
+}
+
+/* Math styling */
+.math {
+    font-size: 1.1em;
+}