Skip to content

Formalize documentation, CI and PyPI publishing (#48, #49, #50) - #51

Merged
mgraffg merged 10 commits into
developfrom
issues-48-49-50
Nov 20, 2026
Merged

mgraffg merged 10 commits into
developfrom
issues-48-49-50

Conversation

@mgraffg

@mgraffg mgraffg commented Nov 20, 2026

Copy link
Copy Markdown
Member

Summary

Formalizes the project's documentation and release pipeline in three steps, followed by six review fixes on the same branch.

#48 — Replace legacy CI with pytest and a tag-driven PyPI publish workflow

  • .github/workflows/test.yml runs pytest CompStats on Python 3.10–3.12, collects coverage and runs the version gate scripts/check_package_versions.py (the local __version__ must be exactly one patch or one minor release ahead of PyPI).
  • .github/workflows/publish-pypi.yml publishes to PyPI when a v<__version__> tag is pushed, after checking that the tag equals __version__.
  • The legacy workflows (test.yaml, pip.yaml) are removed; CompStats/tests/test_packaging.py covers the packaging metadata.

#49 — Make the Sphinx developer reference formal and strict-build clean

  • The developer reference under docs/source/ builds with sphinx -n -W --keep-going without warnings; CI runs that same command.
  • Only docstring text changed under CompStats/ (no executable code); the shared docstring template in metrics_docs was fixed first.
  • ReadTheDocs is dropped (.readthedocs.yaml removed); the developer reference is published on GitHub Pages under /dev/.

#50 — Formalize the Quarto user site and README, and publish both doc sites to GitHub Pages

Review fixes

Commits

Verification

  • MPLBACKEND=Agg .venv/bin/python -m pytest CompStats: 104 passed (run on the branch tip before opening this pull request). On macOS the suite needs MPLBACKEND=Agg; without it plt.show() blocks.
  • Not verified here: the Colab install cell was never executed (it is #| eval: false), and the GitHub Pages deployment only runs on main.

After merging

  • This pull request targets develop, which is not the default branch, so GitHub will not close the issues on merge.
  • Publishing the site requires enabling GitHub Pages with "GitHub Actions" as the source, and merging to main.
  • Publishing to PyPI requires pushing the tag v0.2.0 after the merge to main.

Closes #48
Closes #49
Closes #50
Closes #45
Closes #46

🤖 Generated with Claude Code

mgraffg and others added 10 commits November 19, 2026 16:27
…(issue #48)

- test.yml runs pytest on Python 3.10-3.12, Coveralls coverage and the
  PyPI version gate; publish-pypi.yml verifies the v* tag against
  __version__, builds sdist+wheel, runs twine check and uploads.
- Add scripts/check_package_versions.py, [build-system] and a `test` extra.
- Add CompStats/tests/test_packaging.py; update badge URLs and CLAUDE.md
  (new Releasing section); drop the stale nosetests.xml ignore line.

Verification notes: `python -m build` is not installed in .venv (the issue
assumed it was) and nothing may be installed, so the build was checked by
calling setuptools.build_meta.build_sdist/build_wheel on a scratch copy:
compstats-0.2.0.tar.gz and compstats-0.2.0-py3-none-any.whl built.
check_package_versions.py printed "OK: ok" (pypi 0.1.15, local 0.2.0).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…sue #49)

- Rewrite docs/source/conf.py (furo, no sys.path, intersphinx for python,
  numpy, pandas, scipy, sklearn, statsmodels, seaborn, matplotlib); add
  docs/requirements.txt and utils_api.rst; drop .readthedocs.yaml.
- Restructure index.rst (introduction, statistical background, architecture,
  invariants, development, citing with both papers); update metrics_api.rst
  and performance_api.rst.
- Fix all 258 strict-build warnings by editing docstring text only:
  parameter names and .measure factories become inline literals (including
  the metrics_docs template), unqualified/abbreviated type names are
  qualified, malformed reST in performance.py is repaired; improve the weak
  docstrings listed in the issue. No executable code changed (verified by
  comparing the ASTs with docstrings stripped; only the metrics_docs
  template string differs).
- Add the `docs` job (strict build) to test.yml and CompStats/tests/test_docs.py;
  update CLAUDE.md.

`python -m sphinx -n -W --keep-going -b html docs/source docs/build/html`
ends with "build succeeded." and no warning.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… to GitHub Pages (issue #50)

- Quarto: new navbar, home page as index.qmd, new Install, Methodology and
  Citing pages; the Colab install cells are shown but not executed
  (#| eval: false); sklearn_users is seeded and ends with the comparison
  against the best system; quarto/_freeze refreshed so CI renders without
  Python.
- README.rst rewritten (short, formal, no images); pyproject URLs point at
  the GitHub Pages site; legacy docs/*.ipynb removed.
- website.yml replaces publish.yml: renders the site from the freeze, builds
  the Sphinx reference into /dev/ and deploys with actions/deploy-pages from
  main.
- CLAUDE.md gets a Documentation section; docs/source/index.rst documents the
  user-site preview; test_docs.py gains the freeze, navbar, README, workflow
  and project-URL tests.

Verified: the executing render, the render with QUARTO_PYTHON=/nonexistent
(no kernel started, freeze unchanged), the strict Sphinx build into
quarto/_site/dev, docutils on README.rst, and the full pytest suite.

Closes #45
Closes #46

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
#48 #49 #50)

Corrects a review finding found after the fact; these edits are not part of
the original issues and must not be reverted as redundant.

- Remove the "developed by INGEOTEC" attribution from the home page and the
  INGEOTEC mention from the site footer (authors named instead).
- Replace "validated on eight competitions" with the article's wording
  (designed to be universally applicable, illustrated with eight cases).
- State why classical tests do not apply (Dietterich 1998, Demsar 2006) and
  the purpose of the methodology on the home page and in the README.
- Methodology page: hypotheses and partial-overlap reading, 0.05 decision rule
  and rationale of the paired bootstrap (Koehn 2004), reasons for multiple
  comparison correction, competitiveness restructured into three aspects with
  PPI separated as potential for improvement; add three references.
- docs/source/index.rst: same competitiveness correction.
- test_packaging.py no longer contains the legacy strings it checks for;
  add test_site_follows_the_article.

Verified: strict Sphinx build, README with docutils, render from the freeze
without Python (freeze unchanged), full suite 100 passed (run with
MPLBACKEND=Agg, as CI does; the macOS GUI backend blocks in plt.show()).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…-2: #50)

Corrects a review finding found after the fact: citations were plain text and
the reader had no link to the full reference. Not part of the original issue;
do not revert as redundant.

- Add quarto/references.bib and `bibliography: references.bib`; citations on
  the home and methodology pages are now `[@key]` links to complete entries
  (authors, title, venue, volume, pages, DOI or URL), and the hand-written
  reference list is replaced by the generated one.
- Add volume and pages of the 2024 article to the BibTeX in citing.qmd and
  README.rst.
- test_docs.py: methodology test checks citation through the bibliography;
  new test_site_bibliography.

Verified: render from the freeze without Python (freeze unchanged), citation
targets present, README valid, full suite 101 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e (review fix-3: #50)

Corrects a review finding found after the fact: the arXiv link of the 2024
article was typed in the home page prose instead of being part of its
reference. Not part of the original issue; do not revert as redundant.

- Add quarto/compstats.csl (author-date, prints the BibTeX `note` field,
  which Quarto's default Chicago style does not) and `csl: compstats.csl`.
- references.bib: `note` with the preprint URL for Nava-Munoz2024; double
  braces around the Efron1994 publisher.
- index.qmd: drop the hand-typed preprint link.
- test_site_bibliography checks the style, the note and the absence of the
  link in the prose.

Verified: render from the freeze without Python (freeze unchanged), preprint
link inside the reference entry on both pages, full suite 101 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Corrects a review finding found after the fact: every code cell of the three
notebook pages was collapsed behind a "Code" link. Not part of the original
issue; do not revert as redundant.

- Remove `code-fold: true` from quarto/_quarto.yml (Quarto's default shows
  the code unfolded).
- Add test_site_code_is_visible.

Verified: render from the freeze without Python (freeze unchanged), no
code-fold in the three notebook pages and the code still present, full suite
102 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…fix-5: #50)

Corrects a review finding found after the fact; these edits are not part of
the original issue and must not be reverted as redundant.

- Colab install cell of the three notebooks: `try: import CompStats / except
  ImportError:` guard that installs with `uv pip install -q --system`, falling
  back to pip; still `#| eval: false`.
- sklearn_users.ipynb: explain `statistic` and `se` of the first output,
  explain the figure of "Rest of the classifiers", state that the package is
  not limited to classification and add a Regression section (diabetes,
  mean_absolute_error, plot, Holm-adjusted p-values).
- quarto/_freeze regenerated; test_docs.py and CLAUDE.md follow the new
  install cell; new test_sklearn_users_covers_regression.

Verified: executing render, then render without Python with the freeze
unchanged, inserted sentences checked against the regenerated outputs, full
suite 103 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…w fix-6: #50)

Corrects a review finding found after the fact: the prose joined clauses with
semicolons, colons and dashes far more often than the published article. Not
part of the original issue; do not revert as redundant.

- index.qmd, install.qmd, methodology.qmd, the markdown cells of the three
  notebooks and the prose of README.rst: one idea per sentence, sentence-initial
  connectors or subordination instead of semicolons, colons only before
  enumerations, no dashes as punctuation. Meaning, numbers, code, formulas,
  headings and citations are unchanged.
- Notebooks edited only in markdown cells through nbformat (code cells
  verified identical); quarto/_freeze regenerated.
- test_site_prose_style enforces the punctuation limits; CLAUDE.md gets the
  rule. The test helper now skips Jupyter's .ipynb_checkpoints directories.

Verified: executing render, then render without Python with the freeze
unchanged, outputs quoted by the text unchanged, full suite 104 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@mgraffg
mgraffg merged commit d5ac79d into develop Nov 20, 2026
8 of 9 checks passed
@mgraffg
mgraffg deleted the issues-48-49-50 branch November 20, 2026 16:35
mgraffg added a commit that referenced this pull request Nov 20, 2026
* Crear la plantilla del sitio en Quarto (estructura tipo LegalIA) y la página de Introducción

Migra quarto/ de un dashboard de una sola página a un proyecto Quarto
de tipo website: _quarto.yml con navbar/footer/tema propio, index.ipynb
como libreta de inicio con la Introducción basada en el artículo
(arXiv:2403.04693) y las tarjetas de instalación, y pages/ como
destino para las libretas que agregarán #38, #39 y #40.

Closes #43

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Agregar identificadores únicos a las celdas de markdown y actualizar la información del lenguaje en el notebook de Quarto

* Crear la página 'scikit-learn Users' (libreta) con la API actual (closes #38)

Migra la sección "scikit-learn Users" del borrador anterior
(quarto/CompStats.qmd) a quarto/pages/sklearn_users.ipynb, siguiendo el
formato de libreta/website adoptado en #43. Los ejemplos ya usaban la API
actual (func/BiB vía CompStats.metrics.f1_score); el flujo se verificó
ejecutando con `quarto render`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Crear la página 'Competition Organizers' (libreta) usando el dataset de INGEOTEC/Delitos (closes #39)

Sólo las etiquetas del corpus son redistribuibles (no el texto de los
tuits, por los términos de servicio de Twitter/X), así que la libreta
descarga las etiquetas de la partición de prueba y simula cuatro
"submissions" con distinto nivel de acierto para ilustrar el flujo de
un organizador: construir el leaderboard con f1_score, revisar los
intervalos de confianza, y calcular difference()/p-values respecto al
mejor.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Expandir la libreta 'Competition Organizers' a cinco competidores y agregar corrección por comparaciones múltiples

Reemplaza el baseline de clase mayoritaria por un quinto equipo simulado,
de modo que Team Alpha y Team Beta comparten el mismo nivel de habilidad
(pero con predicciones distintas, no idénticas) y quedan estadísticamente
empatados en primer lugar, mientras que Team Gamma, Team Delta y Team
Epsilon son competitivos pero con rendimiento menor. Se fija la semilla
del remuestreo bootstrap (np.random.seed) para que el resultado sea
reproducible: Team Gamma queda significativamente por debajo del mejor
con el p-value crudo, Holm y FDR, pero empatado bajo la corrección de
Bonferroni, lo que ilustra cómo cambian tanto los p-values como las
gráficas (Perf.plot/Difference.plot) según el método de corrección
usado.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Crear la página 'Multiple Testing' (libreta) con ejemplo de tres métricas de rendimiento

Muestra un Perf multi-medida (precision, recall, F1) sobre tres sistemas
sintéticos con distinto trade-off precision/recall, donde cada uno gana
en una métrica distinta, y usa Difference.p_value(correction=...) para
corregir por comparaciones múltiples entre medidas (closes #40)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Reestructurar docs/source/index.rst como documentación de desarrollo

La página principal de Sphinx deja de ser el tutorial completo (Quickstart
Guide con la API funcional antigua de performance()) y pasa a incluir una
introducción breve, una nota que remite al sitio de Quarto para el tutorial
de uso, y la arquitectura interna (antes en architecture.rst, ahora fusionada
en index.rst) como documentación orientada a quien contribuye al código.
También se agrega el docstring faltante en StatisticSamples.__getitem__.

Closes #44

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Enlazar el sitio principal (Quarto) con la documentación de la API en ReadTheDocs

Se agrega un enlace "API Docs" en el navbar de quarto/_quarto.yml hacia
https://compstats.readthedocs.io/en/latest/. El enlace de vuelta desde
Sphinx hacia https://ingeotec.github.io/CompStats/ ya existía en
docs/source/index.rst (agregado al cerrar #44).

Closes #42

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Agregar enlaces 'Open in Colab' a las libretas del sitio (closes #41)

Cada libreta bajo quarto/ (index.ipynb y pages/*.ipynb) recibe un badge que
enlaza al notebook crudo en la rama main para abrirlo directamente en Colab.
Las tres libretas con código (sklearn_users, competition_organizers,
multiple_testing) también reciben una celda `pip install -q CompStats` al
inicio, ya que Colab no trae el paquete preinstalado; el resto de sus
dependencias (seaborn, statsmodels, pandas) llegan de forma transitiva por
ser dependencias declaradas de CompStats en pyproject.toml.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Configure issue-pilot for this repository (#47)

* Formalize documentation, CI and PyPI publishing (#48, #49, #50) (#51)

* Replace legacy CI with pytest and a tag-driven PyPI publish workflow (issue #48)

- test.yml runs pytest on Python 3.10-3.12, Coveralls coverage and the
  PyPI version gate; publish-pypi.yml verifies the v* tag against
  __version__, builds sdist+wheel, runs twine check and uploads.
- Add scripts/check_package_versions.py, [build-system] and a `test` extra.
- Add CompStats/tests/test_packaging.py; update badge URLs and CLAUDE.md
  (new Releasing section); drop the stale nosetests.xml ignore line.

Verification notes: `python -m build` is not installed in .venv (the issue
assumed it was) and nothing may be installed, so the build was checked by
calling setuptools.build_meta.build_sdist/build_wheel on a scratch copy:
compstats-0.2.0.tar.gz and compstats-0.2.0-py3-none-any.whl built.
check_package_versions.py printed "OK: ok" (pypi 0.1.15, local 0.2.0).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Make the Sphinx developer reference formal and strict-build clean (issue #49)

- Rewrite docs/source/conf.py (furo, no sys.path, intersphinx for python,
  numpy, pandas, scipy, sklearn, statsmodels, seaborn, matplotlib); add
  docs/requirements.txt and utils_api.rst; drop .readthedocs.yaml.
- Restructure index.rst (introduction, statistical background, architecture,
  invariants, development, citing with both papers); update metrics_api.rst
  and performance_api.rst.
- Fix all 258 strict-build warnings by editing docstring text only:
  parameter names and .measure factories become inline literals (including
  the metrics_docs template), unqualified/abbreviated type names are
  qualified, malformed reST in performance.py is repaired; improve the weak
  docstrings listed in the issue. No executable code changed (verified by
  comparing the ASTs with docstrings stripped; only the metrics_docs
  template string differs).
- Add the `docs` job (strict build) to test.yml and CompStats/tests/test_docs.py;
  update CLAUDE.md.

`python -m sphinx -n -W --keep-going -b html docs/source docs/build/html`
ends with "build succeeded." and no warning.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Formalize the Quarto user site and README, and publish both doc sites to GitHub Pages (issue #50)

- Quarto: new navbar, home page as index.qmd, new Install, Methodology and
  Citing pages; the Colab install cells are shown but not executed
  (#| eval: false); sklearn_users is seeded and ends with the comparison
  against the best system; quarto/_freeze refreshed so CI renders without
  Python.
- README.rst rewritten (short, formal, no images); pyproject URLs point at
  the GitHub Pages site; legacy docs/*.ipynb removed.
- website.yml replaces publish.yml: renders the site from the freeze, builds
  the Sphinx reference into /dev/ and deploys with actions/deploy-pages from
  main.
- CLAUDE.md gets a Documentation section; docs/source/index.rst documents the
  user-site preview; test_docs.py gains the freeze, navbar, README, workflow
  and project-URL tests.

Verified: the executing render, the render with QUARTO_PYTHON=/nonexistent
(no kernel started, freeze unchanged), the strict Sphinx build into
quarto/_site/dev, docutils on README.rst, and the full pytest suite.

Closes #45
Closes #46

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Align the documentation prose with the published article (review fix-1: #48 #49 #50)

Corrects a review finding found after the fact; these edits are not part of
the original issues and must not be reverted as redundant.

- Remove the "developed by INGEOTEC" attribution from the home page and the
  INGEOTEC mention from the site footer (authors named instead).
- Replace "validated on eight competitions" with the article's wording
  (designed to be universally applicable, illustrated with eight cases).
- State why classical tests do not apply (Dietterich 1998, Demsar 2006) and
  the purpose of the methodology on the home page and in the README.
- Methodology page: hypotheses and partial-overlap reading, 0.05 decision rule
  and rationale of the paired bootstrap (Koehn 2004), reasons for multiple
  comparison correction, competitiveness restructured into three aspects with
  PPI separated as potential for improvement; add three references.
- docs/source/index.rst: same competitiveness correction.
- test_packaging.py no longer contains the legacy strings it checks for;
  add test_site_follows_the_article.

Verified: strict Sphinx build, README with docutils, render from the freeze
without Python (freeze unchanged), full suite 100 passed (run with
MPLBACKEND=Agg, as CI does; the macOS GUI backend blocks in plt.show()).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Cite works on the user site through Quarto's bibliography (review fix-2: #50)

Corrects a review finding found after the fact: citations were plain text and
the reader had no link to the full reference. Not part of the original issue;
do not revert as redundant.

- Add quarto/references.bib and `bibliography: references.bib`; citations on
  the home and methodology pages are now `[@key]` links to complete entries
  (authors, title, venue, volume, pages, DOI or URL), and the hand-written
  reference list is replaced by the generated one.
- Add volume and pages of the 2024 article to the BibTeX in citing.qmd and
  README.rst.
- test_docs.py: methodology test checks citation through the bibliography;
  new test_site_bibliography.

Verified: render from the freeze without Python (freeze unchanged), citation
targets present, README valid, full suite 101 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Carry the preprint link in the bibliography with a site citation style (review fix-3: #50)

Corrects a review finding found after the fact: the arXiv link of the 2024
article was typed in the home page prose instead of being part of its
reference. Not part of the original issue; do not revert as redundant.

- Add quarto/compstats.csl (author-date, prints the BibTeX `note` field,
  which Quarto's default Chicago style does not) and `csl: compstats.csl`.
- references.bib: `note` with the preprint URL for Nava-Munoz2024; double
  braces around the Efron1994 publisher.
- index.qmd: drop the hand-typed preprint link.
- test_site_bibliography checks the style, the note and the absence of the
  link in the prose.

Verified: render from the freeze without Python (freeze unchanged), preprint
link inside the reference entry on both pages, full suite 101 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Show all code on the user site without a fold link (review fix-4: #50)

Corrects a review finding found after the fact: every code cell of the three
notebook pages was collapsed behind a "Code" link. Not part of the original
issue; do not revert as redundant.

- Remove `code-fold: true` from quarto/_quarto.yml (Quarto's default shows
  the code unfolded).
- Add test_site_code_is_visible.

Verified: render from the freeze without Python (freeze unchanged), no
code-fold in the three notebook pages and the code still present, full suite
102 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Improve the scikit-learn tutorial and the Colab install cell (review fix-5: #50)

Corrects a review finding found after the fact; these edits are not part of
the original issue and must not be reverted as redundant.

- Colab install cell of the three notebooks: `try: import CompStats / except
  ImportError:` guard that installs with `uv pip install -q --system`, falling
  back to pip; still `#| eval: false`.
- sklearn_users.ipynb: explain `statistic` and `se` of the first output,
  explain the figure of "Rest of the classifiers", state that the package is
  not limited to classification and add a Regression section (diabetes,
  mean_absolute_error, plot, Holm-adjusted p-values).
- quarto/_freeze regenerated; test_docs.py and CLAUDE.md follow the new
  install cell; new test_sklearn_users_covers_regression.

Verified: executing render, then render without Python with the freeze
unchanged, inserted sentences checked against the regenerated outputs, full
suite 103 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Actualizar metadatos en el cuaderno de scikit-learn para evitar colapsar las celdas

* Rewrite the site prose in the punctuation style of the article (review fix-6: #50)

Corrects a review finding found after the fact: the prose joined clauses with
semicolons, colons and dashes far more often than the published article. Not
part of the original issue; do not revert as redundant.

- index.qmd, install.qmd, methodology.qmd, the markdown cells of the three
  notebooks and the prose of README.rst: one idea per sentence, sentence-initial
  connectors or subordination instead of semicolons, colons only before
  enumerations, no dashes as punctuation. Meaning, numbers, code, formulas,
  headings and citations are unchanged.
- Notebooks edited only in markdown cells through nbformat (code cells
  verified identical); quarto/_freeze regenerated.
- test_site_prose_style enforces the punctuation limits; CLAUDE.md gets the
  rule. The test helper now skips Jupyter's .ipynb_checkpoints directories.

Verified: executing render, then render without Python with the freeze
unchanged, outputs quoted by the text unchanged, full suite 104 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
mgraffg added a commit that referenced this pull request Nov 21, 2026
* Crear la plantilla del sitio en Quarto (estructura tipo LegalIA) y la página de Introducción

Migra quarto/ de un dashboard de una sola página a un proyecto Quarto
de tipo website: _quarto.yml con navbar/footer/tema propio, index.ipynb
como libreta de inicio con la Introducción basada en el artículo
(arXiv:2403.04693) y las tarjetas de instalación, y pages/ como
destino para las libretas que agregarán #38, #39 y #40.

Closes #43

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Agregar identificadores únicos a las celdas de markdown y actualizar la información del lenguaje en el notebook de Quarto

* Crear la página 'scikit-learn Users' (libreta) con la API actual (closes #38)

Migra la sección "scikit-learn Users" del borrador anterior
(quarto/CompStats.qmd) a quarto/pages/sklearn_users.ipynb, siguiendo el
formato de libreta/website adoptado en #43. Los ejemplos ya usaban la API
actual (func/BiB vía CompStats.metrics.f1_score); el flujo se verificó
ejecutando con `quarto render`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Crear la página 'Competition Organizers' (libreta) usando el dataset de INGEOTEC/Delitos (closes #39)

Sólo las etiquetas del corpus son redistribuibles (no el texto de los
tuits, por los términos de servicio de Twitter/X), así que la libreta
descarga las etiquetas de la partición de prueba y simula cuatro
"submissions" con distinto nivel de acierto para ilustrar el flujo de
un organizador: construir el leaderboard con f1_score, revisar los
intervalos de confianza, y calcular difference()/p-values respecto al
mejor.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Expandir la libreta 'Competition Organizers' a cinco competidores y agregar corrección por comparaciones múltiples

Reemplaza el baseline de clase mayoritaria por un quinto equipo simulado,
de modo que Team Alpha y Team Beta comparten el mismo nivel de habilidad
(pero con predicciones distintas, no idénticas) y quedan estadísticamente
empatados en primer lugar, mientras que Team Gamma, Team Delta y Team
Epsilon son competitivos pero con rendimiento menor. Se fija la semilla
del remuestreo bootstrap (np.random.seed) para que el resultado sea
reproducible: Team Gamma queda significativamente por debajo del mejor
con el p-value crudo, Holm y FDR, pero empatado bajo la corrección de
Bonferroni, lo que ilustra cómo cambian tanto los p-values como las
gráficas (Perf.plot/Difference.plot) según el método de corrección
usado.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Crear la página 'Multiple Testing' (libreta) con ejemplo de tres métricas de rendimiento

Muestra un Perf multi-medida (precision, recall, F1) sobre tres sistemas
sintéticos con distinto trade-off precision/recall, donde cada uno gana
en una métrica distinta, y usa Difference.p_value(correction=...) para
corregir por comparaciones múltiples entre medidas (closes #40)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Reestructurar docs/source/index.rst como documentación de desarrollo

La página principal de Sphinx deja de ser el tutorial completo (Quickstart
Guide con la API funcional antigua de performance()) y pasa a incluir una
introducción breve, una nota que remite al sitio de Quarto para el tutorial
de uso, y la arquitectura interna (antes en architecture.rst, ahora fusionada
en index.rst) como documentación orientada a quien contribuye al código.
También se agrega el docstring faltante en StatisticSamples.__getitem__.

Closes #44

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Enlazar el sitio principal (Quarto) con la documentación de la API en ReadTheDocs

Se agrega un enlace "API Docs" en el navbar de quarto/_quarto.yml hacia
https://compstats.readthedocs.io/en/latest/. El enlace de vuelta desde
Sphinx hacia https://ingeotec.github.io/CompStats/ ya existía en
docs/source/index.rst (agregado al cerrar #44).

Closes #42

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Agregar enlaces 'Open in Colab' a las libretas del sitio (closes #41)

Cada libreta bajo quarto/ (index.ipynb y pages/*.ipynb) recibe un badge que
enlaza al notebook crudo en la rama main para abrirlo directamente en Colab.
Las tres libretas con código (sklearn_users, competition_organizers,
multiple_testing) también reciben una celda `pip install -q CompStats` al
inicio, ya que Colab no trae el paquete preinstalado; el resto de sus
dependencias (seaborn, statsmodels, pandas) llegan de forma transitiva por
ser dependencias declaradas de CompStats en pyproject.toml.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Configure issue-pilot for this repository (#47)

* Formalize documentation, CI and PyPI publishing (#48, #49, #50) (#51)

* Replace legacy CI with pytest and a tag-driven PyPI publish workflow (issue #48)

- test.yml runs pytest on Python 3.10-3.12, Coveralls coverage and the
  PyPI version gate; publish-pypi.yml verifies the v* tag against
  __version__, builds sdist+wheel, runs twine check and uploads.
- Add scripts/check_package_versions.py, [build-system] and a `test` extra.
- Add CompStats/tests/test_packaging.py; update badge URLs and CLAUDE.md
  (new Releasing section); drop the stale nosetests.xml ignore line.

Verification notes: `python -m build` is not installed in .venv (the issue
assumed it was) and nothing may be installed, so the build was checked by
calling setuptools.build_meta.build_sdist/build_wheel on a scratch copy:
compstats-0.2.0.tar.gz and compstats-0.2.0-py3-none-any.whl built.
check_package_versions.py printed "OK: ok" (pypi 0.1.15, local 0.2.0).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Make the Sphinx developer reference formal and strict-build clean (issue #49)

- Rewrite docs/source/conf.py (furo, no sys.path, intersphinx for python,
  numpy, pandas, scipy, sklearn, statsmodels, seaborn, matplotlib); add
  docs/requirements.txt and utils_api.rst; drop .readthedocs.yaml.
- Restructure index.rst (introduction, statistical background, architecture,
  invariants, development, citing with both papers); update metrics_api.rst
  and performance_api.rst.
- Fix all 258 strict-build warnings by editing docstring text only:
  parameter names and .measure factories become inline literals (including
  the metrics_docs template), unqualified/abbreviated type names are
  qualified, malformed reST in performance.py is repaired; improve the weak
  docstrings listed in the issue. No executable code changed (verified by
  comparing the ASTs with docstrings stripped; only the metrics_docs
  template string differs).
- Add the `docs` job (strict build) to test.yml and CompStats/tests/test_docs.py;
  update CLAUDE.md.

`python -m sphinx -n -W --keep-going -b html docs/source docs/build/html`
ends with "build succeeded." and no warning.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Formalize the Quarto user site and README, and publish both doc sites to GitHub Pages (issue #50)

- Quarto: new navbar, home page as index.qmd, new Install, Methodology and
  Citing pages; the Colab install cells are shown but not executed
  (#| eval: false); sklearn_users is seeded and ends with the comparison
  against the best system; quarto/_freeze refreshed so CI renders without
  Python.
- README.rst rewritten (short, formal, no images); pyproject URLs point at
  the GitHub Pages site; legacy docs/*.ipynb removed.
- website.yml replaces publish.yml: renders the site from the freeze, builds
  the Sphinx reference into /dev/ and deploys with actions/deploy-pages from
  main.
- CLAUDE.md gets a Documentation section; docs/source/index.rst documents the
  user-site preview; test_docs.py gains the freeze, navbar, README, workflow
  and project-URL tests.

Verified: the executing render, the render with QUARTO_PYTHON=/nonexistent
(no kernel started, freeze unchanged), the strict Sphinx build into
quarto/_site/dev, docutils on README.rst, and the full pytest suite.

Closes #45
Closes #46

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Align the documentation prose with the published article (review fix-1: #48 #49 #50)

Corrects a review finding found after the fact; these edits are not part of
the original issues and must not be reverted as redundant.

- Remove the "developed by INGEOTEC" attribution from the home page and the
  INGEOTEC mention from the site footer (authors named instead).
- Replace "validated on eight competitions" with the article's wording
  (designed to be universally applicable, illustrated with eight cases).
- State why classical tests do not apply (Dietterich 1998, Demsar 2006) and
  the purpose of the methodology on the home page and in the README.
- Methodology page: hypotheses and partial-overlap reading, 0.05 decision rule
  and rationale of the paired bootstrap (Koehn 2004), reasons for multiple
  comparison correction, competitiveness restructured into three aspects with
  PPI separated as potential for improvement; add three references.
- docs/source/index.rst: same competitiveness correction.
- test_packaging.py no longer contains the legacy strings it checks for;
  add test_site_follows_the_article.

Verified: strict Sphinx build, README with docutils, render from the freeze
without Python (freeze unchanged), full suite 100 passed (run with
MPLBACKEND=Agg, as CI does; the macOS GUI backend blocks in plt.show()).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Cite works on the user site through Quarto's bibliography (review fix-2: #50)

Corrects a review finding found after the fact: citations were plain text and
the reader had no link to the full reference. Not part of the original issue;
do not revert as redundant.

- Add quarto/references.bib and `bibliography: references.bib`; citations on
  the home and methodology pages are now `[@key]` links to complete entries
  (authors, title, venue, volume, pages, DOI or URL), and the hand-written
  reference list is replaced by the generated one.
- Add volume and pages of the 2024 article to the BibTeX in citing.qmd and
  README.rst.
- test_docs.py: methodology test checks citation through the bibliography;
  new test_site_bibliography.

Verified: render from the freeze without Python (freeze unchanged), citation
targets present, README valid, full suite 101 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Carry the preprint link in the bibliography with a site citation style (review fix-3: #50)

Corrects a review finding found after the fact: the arXiv link of the 2024
article was typed in the home page prose instead of being part of its
reference. Not part of the original issue; do not revert as redundant.

- Add quarto/compstats.csl (author-date, prints the BibTeX `note` field,
  which Quarto's default Chicago style does not) and `csl: compstats.csl`.
- references.bib: `note` with the preprint URL for Nava-Munoz2024; double
  braces around the Efron1994 publisher.
- index.qmd: drop the hand-typed preprint link.
- test_site_bibliography checks the style, the note and the absence of the
  link in the prose.

Verified: render from the freeze without Python (freeze unchanged), preprint
link inside the reference entry on both pages, full suite 101 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Show all code on the user site without a fold link (review fix-4: #50)

Corrects a review finding found after the fact: every code cell of the three
notebook pages was collapsed behind a "Code" link. Not part of the original
issue; do not revert as redundant.

- Remove `code-fold: true` from quarto/_quarto.yml (Quarto's default shows
  the code unfolded).
- Add test_site_code_is_visible.

Verified: render from the freeze without Python (freeze unchanged), no
code-fold in the three notebook pages and the code still present, full suite
102 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Improve the scikit-learn tutorial and the Colab install cell (review fix-5: #50)

Corrects a review finding found after the fact; these edits are not part of
the original issue and must not be reverted as redundant.

- Colab install cell of the three notebooks: `try: import CompStats / except
  ImportError:` guard that installs with `uv pip install -q --system`, falling
  back to pip; still `#| eval: false`.
- sklearn_users.ipynb: explain `statistic` and `se` of the first output,
  explain the figure of "Rest of the classifiers", state that the package is
  not limited to classification and add a Regression section (diabetes,
  mean_absolute_error, plot, Holm-adjusted p-values).
- quarto/_freeze regenerated; test_docs.py and CLAUDE.md follow the new
  install cell; new test_sklearn_users_covers_regression.

Verified: executing render, then render without Python with the freeze
unchanged, inserted sentences checked against the regenerated outputs, full
suite 103 passed (MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Actualizar metadatos en el cuaderno de scikit-learn para evitar colapsar las celdas

* Rewrite the site prose in the punctuation style of the article (review fix-6: #50)

Corrects a review finding found after the fact: the prose joined clauses with
semicolons, colons and dashes far more often than the published article. Not
part of the original issue; do not revert as redundant.

- index.qmd, install.qmd, methodology.qmd, the markdown cells of the three
  notebooks and the prose of README.rst: one idea per sentence, sentence-initial
  connectors or subordination instead of semicolons, colons only before
  enumerations, no dashes as punctuation. Meaning, numbers, code, formulas,
  headings and citations are unchanged.
- Notebooks edited only in markdown cells through nbformat (code cells
  verified identical); quarto/_freeze regenerated.
- test_site_prose_style enforces the punctuation limits; CLAUDE.md gets the
  rule. The test helper now skips Jupyter's .ipynb_checkpoints directories.

Verified: executing render, then render without Python with the freeze
unchanged, outputs quoted by the text unchanged, full suite 104 passed
(MPLBACKEND=Agg).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

* Publish to PyPI only on manual dispatch

Remove the tag trigger of publish-pypi.yml, and the tag/version check
that depended on it, so that creating a tag or a GitHub release no
longer tries to upload to PyPI. Update the release instructions and
the workflow test accordingly.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant