Merge branch 'main' into feat/improve-sphinx

Author: DiogoRibeiro7

CITATION.cff

@@ -5,7 +5,7 @@ message: "If you use this software, please cite it using the metadata below."
 preferred-citation:
   type: software
   title: "gen_surv"
-  version: "1.0.0"
+  version: "1.0.3"
   url: "https://github.com/DiogoRibeiro7/genSurvPy"
   authors:
     - family-names: Ribeiro

README.md

@@ -91,26 +91,34 @@ genSurvPy/
 │   ├── 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
-├── LICENSE
-├── .gitignore
+├── LICENCE
+└── .gitignore
 ```
 
 ## 🧠 License
 
-MIT License. See [LICENSE](LICENSE) for details.
+MIT License. See [LICENCE](LICENCE) for details.
 
 
 ## 🔖 Release Process
@@ -130,8 +138,25 @@ expectations for participants in this project.
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up your environment, running tests, and submitting pull requests.
 
+## 🔧 Development Tasks
+
+Common project commands are defined in [`tasks.py`](tasks.py) and can be executed with [Invoke](https://www.pyinvoke.org/):
+
+```bash
+poetry run inv -l  # list available tasks
+poetry run inv test  # run the test suite
+```
+
 ## 📑 Citation
 
 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.
+
+## Author
+
+**Diogo Ribeiro** — [ESMAD - Instituto Politécnico do Porto](https://esmad.ipp.pt)
+
+- ORCID: <https://orcid.org/0009-0001-2022-7072>
+- Professional email: <[email protected]>
+- Personal email: <[email protected]>

docs/source/conf.py

@@ -12,7 +12,7 @@
 project = 'gen_surv'
 copyright = '2025, Diogo Ribeiro'
 author = 'Diogo Ribeiro'
-release = '0.6.3'
+release = '1.0.3'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/index.md

@@ -64,9 +64,37 @@ Generate datasets directly from the terminal:
 python -m gen_surv dataset aft_ln --n 100 > data.csv
 ```
 
+## Repository Layout
+
+```text
+genSurvPy/
+├── gen_surv/
+│   └── ...
+├── tests/
+├── examples/
+├── docs/
+├── scripts/
+├── tasks.py
+└── TODO.md
+```
+
 ## 🔗 Project Links
 
 - [Source Code](https://github.com/DiogoRibeiro7/genSurvPy)
-- [License](https://github.com/DiogoRibeiro7/genSurvPy/blob/main/LICENSE)
+- [License](https://github.com/DiogoRibeiro7/genSurvPy/blob/main/LICENCE)
 - [Code of Conduct](https://github.com/DiogoRibeiro7/genSurvPy/blob/main/CODE_OF_CONDUCT.md)
 
+
+## Citation
+
+If you use **gen_surv** in your work, please cite it using the metadata in
+[CITATION.cff](../../CITATION.cff).
+
+## Author
+
+**Diogo Ribeiro** — [ESMAD - Instituto Politécnico do Porto](https://esmad.ipp.pt)
+
+- ORCID: <https://orcid.org/0009-0001-2022-7072>
+- Professional email: <[email protected]>
+- Personal email: <[email protected]>
+

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "gen_surv"
-version = "1.0.5"
+version = "1.0.7"
 description = "A Python package for simulating survival data, inspired by the R package genSurv"
 authors = ["Diogo Ribeiro <[email protected]>"]
 license = "MIT"

scripts/check_version_match.py

@@ -1,52 +1,62 @@
 #!/usr/bin/env python3
-"""Check that pyproject version matches the latest git tag."""
+"""Check that pyproject version matches the latest git tag. Optionally fix it by tagging."""
 from pathlib import Path
 import subprocess
 import sys
+
 if sys.version_info >= (3, 11):
     import tomllib as tomli
 else:
     import tomli
 
-
 ROOT = Path(__file__).resolve().parents[1]
 
-
 def pyproject_version() -> str:
     pyproject_path = ROOT / "pyproject.toml"
     with pyproject_path.open("rb") as f:
         data = tomli.load(f)
     return data["tool"]["poetry"]["version"]
 
-
 def latest_tag() -> str:
     try:
         tag = subprocess.check_output(
             ["git", "describe", "--tags", "--abbrev=0"], cwd=ROOT, text=True
         ).strip()
         return tag.lstrip("v")
     except subprocess.CalledProcessError:
-        return "0.0.0"
+        return ""
 
+def create_tag(version: str) -> None:
+    print(f"Tagging repository with version: v{version}")
+    subprocess.run(["git", "tag", f"v{version}"], cwd=ROOT, check=True)
+    subprocess.run(["git", "push", "origin", f"v{version}"], cwd=ROOT, check=True)
+    print(f"✅ Git tag v{version} created and pushed.")
 
 def main() -> int:
-    tag = latest_tag()
+    fix = "--fix" in sys.argv
     version = pyproject_version()
+    tag = latest_tag()
 
     if not tag:
-        print("No git tag found", file=sys.stderr)
-        return 1
+        print("⚠️  No git tag found.", file=sys.stderr)
+        if fix:
+            create_tag(version)
+            return 0
+        else:
+            return 1
 
     if version != tag:
         print(
-            f"Version mismatch: pyproject.toml has {version} but latest tag is {tag}",
+            f"❌ Version mismatch: pyproject.toml has {version} but latest tag is {tag}",
             file=sys.stderr,
         )
+        if fix:
+            create_tag(version)
+            return 0
         return 1
 
-    print(f"Version matches latest tag: {version}")
+    print(f"✔️  Version matches latest tag: {version}")
     return 0
 
-
 if __name__ == "__main__":
     sys.exit(main())

tasks.py

@@ -8,16 +8,15 @@
 
 @task
 def test(c: Context) -> None:
-    """
-    Run pytest via Poetry with coverage reporting for the 'gen_surv' package.
+    """Run the test suite with coverage reporting.
+
+    This task executes ``pytest`` and generates a coverage report.
 
-    This task will:
-      1. Execute 'pytest' through Poetry.
-      2. Generate a terminal coverage report.
-      3. Write an XML coverage report to 'coverage.xml'.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke context used to run shell commands.
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Ensure we were passed a valid Context object.
     if not isinstance(c, Context):
@@ -52,16 +51,16 @@ def test(c: Context) -> None:
 
 @task
 def checkversion(c: Context) -> None:
-    """Validate that ``pyproject.toml`` matches the latest git tag.
+    """Check that ``pyproject.toml`` matches the latest Git tag.
 
-    This task runs the ``scripts/check_version_match.py`` helper using Poetry
-    and reports whether the version numbers are aligned.
+    This task executes ``scripts/check_version_match.py`` to ensure the version
+    declared in ``pyproject.toml`` agrees with the most recent tag.
 
     Args:
         c: Invoke context used to run shell commands.
 
-    Returns:
-        None
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     if not isinstance(c, Context):
         raise TypeError(f"Expected Invoke Context, got {type(c).__name__!r}")
@@ -79,17 +78,13 @@ def checkversion(c: Context) -> None:
 
 @task
 def docs(c: Context) -> None:
-    """
-    Build Sphinx documentation for the project using Poetry.
+    """Build the Sphinx documentation.
 
-    This task will:
-      1. Run 'sphinx-build' via Poetry.
-      2. Read source files from 'docs/source'.
-      3. Output HTML (or other format) into 'docs/build'.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke context, used to run shell commands.
-    :type c: Context
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Verify we have a proper Invoke Context.
     if not isinstance(c, Context):
@@ -118,15 +113,13 @@ def docs(c: Context) -> None:
 
 @task
 def stubs(c: Context) -> None:
-    """
-    Generate type stubs for the 'gen_surv' package using stubgen and Poetry.
+    """Generate type stubs for the ``gen_surv`` package.
 
-    This task will:
-      1. Run 'stubgen' via Poetry to analyze 'gen_surv'.
-      2. Output the generated stubs into the 'stubs' directory.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke context used to run shell commands.
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Verify that 'c' is the correct Invoke Context.
     if not isinstance(c, Context):
@@ -155,15 +148,13 @@ def stubs(c: Context) -> None:
 
 @task
 def build(c: Context) -> None:
-    """
-    Build the project distributions using Poetry.
+    """Build distribution artifacts using Poetry.
 
-    This task will:
-      1. Run 'poetry build' to create source and wheel packages.
-      2. Place the built artifacts in the 'dist/' directory.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke context used to run shell commands.
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Verify that we received a valid Invoke Context.
     if not isinstance(c, Context):
@@ -191,16 +182,10 @@ def build(c: Context) -> None:
 
 @task
 def publish(c: Context) -> None:
-    """
-    Build and publish the package to PyPI using Poetry.
-
-    This task will:
-      1. Build the distribution via 'poetry publish --build'.
-      2. Attach to a pseudo-TTY so you can enter credentials or confirm prompts.
-      3. Not abort immediately if an error occurs; instead, it will print diagnostics.
+    """Build and upload the package to PyPI.
 
-    :param c: Invoke context, used to run shell commands.
-    :type c: Context
+    Args:
+        c: Invoke context used to run shell commands.
     """
     # Run the poetry publish command.
     # - warn=True: do not abort on non-zero exit, so we can inspect and report.
@@ -227,17 +212,13 @@ def publish(c: Context) -> None:
 
 @task
 def clean(c: Context) -> None:
-    """
-    Remove build artifacts, caches, and generated files.
+    """Remove build artifacts and caches.
 
-    This task will:
-      1. Delete the 'dist' and 'build' directories.
-      2. Remove generated documentation in 'docs/build'.
-      3. Clear pytest and mypy caches.
-      4. Delete coverage reports and stub files.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke context used to run shell commands.
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Verify the argument is an Invoke Context.
     if not isinstance(c, Context):
@@ -276,18 +257,13 @@ def clean(c: Context) -> None:
 
 @task
 def gitpush(c: Context) -> None:
-    """
-    Stage all changes, prompt for a commit message, create a signed commit, and push to the remote repository.
+    """Commit and push all staged changes.
 
-    This task will:
-      1. Verify that 'c' is an Invoke Context.
-      2. Run 'git add .' to stage all unstaged changes.
-      3. Prompt the user for a commit message; abort if empty.
-      4. Sanitize the message, then run 'git commit -S -m <message>'.
-      5. Run 'git push' to publish commits.
+    Args:
+        c: Invoke context used to run shell commands.
 
-    :param c: Invoke Context used to run shell commands.
-    :raises TypeError: If 'c' is not an Invoke Context.
+    Raises:
+        TypeError: If ``c`` is not an Invoke :class:`Context`.
     """
     # Verify the argument is a valid Invoke Context.
     if not isinstance(c, Context):