diff --git a/CITATION.cff b/CITATION.cff index 479d864..fe3f8e0 100644 --- a/CITATION.cff +++ b/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 diff --git a/README.md b/README.md index b4f34af..16e7c9c 100644 --- a/README.md +++ b/README.md @@ -87,26 +87,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 @@ -126,8 +134,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: +- Professional email: +- Personal email: diff --git a/docs/source/conf.py b/docs/source/conf.py index cd44dab..a340b59 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -9,10 +9,10 @@ import sys sys.path.insert(0, os.path.abspath('../../gen_surv')) -project = 'gen_suvr' +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 diff --git a/docs/source/index.md b/docs/source/index.md index 83e034d..804e558 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -57,8 +57,35 @@ 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: +- Professional email: +- Personal email: diff --git a/docs/source/modules.md b/docs/source/modules.md index 7e9256f..1dbaeae 100644 --- a/docs/source/modules.md +++ b/docs/source/modules.md @@ -23,9 +23,9 @@ ::: gen_surv.interface options: members: true - undoc-members: tru + undoc-members: true ::: gen_surv.aft options: members: true - undoc-members: true \ No newline at end of file + undoc-members: true diff --git a/tasks.py b/tasks.py index 784e529..d37bc3a 100644 --- a/tasks.py +++ b/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 '. - 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):