Skip to content

Fix task README rendering, deprecate openproblems.docs - #42

Merged
rcannood merged 6 commits into
mainfrom
fix-task-readme-rendering
Jul 29, 2026
Merged

Fix task README rendering, deprecate openproblems.docs#42
rcannood merged 6 commits into
mainfrom
fix-task-readme-rendering

Conversation

@rcannood

@rcannood rcannood commented Jul 29, 2026

Copy link
Copy Markdown
Member

Two bugs in the README rendering, spotted while looking at task_predict_modality. Both are in the python package, which is what common/scripts/create_task_readme runs through openproblems/src/project/render_readme.

Section order

read_task_metadata() picked a single root (in-degree 0) and did a bfs from it. Two consequences:

  • task_predict_modality has two roots (file_common_dataset_mod1 and file_common_dataset_mod2), so only mod1 was reachable and Raw dataset mod2 ended up dead last, after Score -- plus a "Multiple root nodes" warning on every run.
  • A bfs orders by distance from the root, not by dependency, so every task documented Metric before the Prediction file it consumes.

Now sorted with kahn's algorithm seeded with all roots, so nothing is documented before its inputs:

before                          after
file_common_dataset_mod1        file_common_dataset_mod1
comp_process_datasets           file_common_dataset_mod2   <- was stranded at the end
...                             comp_process_datasets
comp_metric                     ...
file_prediction                 comp_method_train
file_pretrained_model           file_pretrained_model
file_score                      comp_method_predict
file_common_dataset_mod2        file_prediction
                                comp_metric
                                file_score

I ran this over all 21 task repos I have checked out locally: no cycles, no dropped nodes, and every one of them moved Metric after its input file. Three repos (task_batch_integration, task_ist_preprocessing, task_workshop_example) error out on both old and new code, because of absolute __merge__ paths in their own yamls -- unrelated.

Missing --seed

render_component_spec() filtered the arguments table down to type: file, which dropped --seed from the process_dataset spec entirely. It also only read summary, which file arguments inherit through __merge__ but plain ones don't have -- that's why the currently published README (generated by the older R code, which didn't filter) shows --seed | integer | NA.

Both fixed, so task_predict_modality now renders:

| `--seed` | `integer` | (_Optional_) The seed for determining the train/test split. Default: `1`. |

Deprecating openproblems.docs

The R package has both bugs too, but nothing outside the package itself calls it -- I grepped openproblems, common_resources and core, and only the python module is wired into render_readme. So rather than backporting, all eight exported functions now warn once per session and point at openproblems.project.docs. render_json_schema_example() has no python counterpart, so it says that instead.

rcannood added 6 commits July 29, 2026 15:14
* Sort the api graph with kahn's algorithm seeded with all roots,
  instead of a bfs from a single root
* Tasks with more than one raw dataset (e.g. task_predict_modality) no
  longer strand all but the first at the very end of the readme
* A component is no longer documented before the files it consumes
* Stop filtering the arguments table down to `type: file`, which dropped
  `--seed` from the process_dataset spec entirely
* Fall back to an argument's `description` when it has no `summary` --
  only file arguments get a summary, through `__merge__`
* Add a `--seed` to the example project to cover both
* Add `.deprecate_docs()`, which warns once per session per function
* Deprecate all eight exported functions; the readme pipeline
  (`common/scripts/create_task_readme`) runs the python implementation,
  so `openproblems.project.docs` is the source of truth now
* `render_json_schema_example()` has no python replacement -- say so
* Note in the changelog that the two readme bugs fixed in python core
  v0.2.0 were not backported here
* styler 1.11.0 puts one argument per line at a single indent with the
  closing `) {` on its own line, where the older styler used a hanging
  double indent -- lintr 3.4.0 flags the latter with indentation_linter
* Pre-existing on main; the R workflow only triggers on `packages/r/**`,
  so this pr is simply the first in a while to run it
…ring' of github.com:openproblems-bio/core into fix-task-readme-rendering
@rcannood
rcannood merged commit 5b802a7 into main Jul 29, 2026
12 checks passed
@rcannood
rcannood deleted the fix-task-readme-rendering branch July 29, 2026 13:41
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