Part of #108 · Phase 5 · label: documentation
Problem
Every cloud configuration example in README.md raises on its first line. configure() has no pass-through for unknown keys — config.py:262 raises ValueError(f"Unknown configuration parameter: {key}") — and the README uses unprefixed names that do not exist.
| README says |
Actual field (config.py) |
access_key_id, secret_access_key, region |
aws_access_key_id, aws_secret_access_key, aws_region (:53-66) |
project_id, service_account_key, region |
gcp_project_id, gcp_service_account_key, gcp_region (:87-90) |
subscription_id, client_id, client_secret, tenant_id |
azure_* (:71-83) |
token |
hf_token (:105) |
Other broken examples:
@cluster(provider='lambda_cloud') / provider='huggingface_spaces' -> ValueError: Unsupported cloud provider. executor_core.py:63 accepts only ["lambda","aws","azure","gcp","huggingface"]. The decorator's own docstring (decorator.py:57) uses the correct short names — the README does not.monitor.get_cost_optimization_recommendations() -> TypeError: missing 2 required positional arguments. Signature is (self, resource_usage, cost_estimate) (cost_monitoring.py:126).@cluster(provider='aws', cluster_type='kubernetes', cluster_name=...) — cluster_type is not a cluster() parameter; it lands silently in **kwargs and configures nothing. machine_type, vm_size, space_hardware are likewise silently absorbed.- README claims "Zero use of
@patch, Mock(), or simulations" — 60 of 240 test files use mocks, 2,513 occurrences, including 3 inside tests/real_world/.
MIGRATION.md is also wrong: it lists from clustrix import ClusterConfig under "These imports continue to work unchanged" — that symbol is not in clustrix/__init__.py at all. It also quotes a testpaths value and marker list that no longer match pyproject.toml.
Version drift — four locations, two values
| File |
Version |
clustrix/__init__.py:64 |
0.1.0 |
docs/source/conf.py:17 |
0.1.0 |
pyproject.toml:7 |
0.1.1 |
setup.py:8 |
0.1.1 |
Both setup.py and pyproject.toml declare name/version/deps independently. The PEP 517 build uses pyproject.toml and silently ignores setup.py, so the metadata you read may not be the metadata that installs.
Docs site
docs/source/api/notebook_magic.rst autodocs ClusterConfigWidget — no such class exists. The real ones are EnhancedClusterConfigWidget (notebook_magic_widget.py:35) and ModernClustrixWidget (modern_notebook_widget.py:24).docs/source/index.rst:23 lists only SLURM/PBS/SGE/Kubernetes/SSH — no cloud — contradicting the README's cloud claims.- Local
sphinx-build fails at conf.py:34 on ModuleNotFoundError: No module named 'sphinx_wagtail_theme' (environment-only; RTD installs it).
Acceptance criteria
Part of #108 · Phase 5 · label: documentation
Problem
Every cloud configuration example in
README.mdraises on its first line.configure()has no pass-through for unknown keys —config.py:262raisesValueError(f"Unknown configuration parameter: {key}")— and the README uses unprefixed names that do not exist.config.py)access_key_id,secret_access_key,regionaws_access_key_id,aws_secret_access_key,aws_region(:53-66)project_id,service_account_key,regiongcp_project_id,gcp_service_account_key,gcp_region(:87-90)subscription_id,client_id,client_secret,tenant_idazure_*(:71-83)tokenhf_token(:105)Other broken examples:
@cluster(provider='lambda_cloud')/provider='huggingface_spaces'->ValueError: Unsupported cloud provider.executor_core.py:63accepts only["lambda","aws","azure","gcp","huggingface"]. The decorator's own docstring (decorator.py:57) uses the correct short names — the README does not.monitor.get_cost_optimization_recommendations()->TypeError: missing 2 required positional arguments. Signature is(self, resource_usage, cost_estimate)(cost_monitoring.py:126).@cluster(provider='aws', cluster_type='kubernetes', cluster_name=...)—cluster_typeis not acluster()parameter; it lands silently in**kwargsand configures nothing.machine_type,vm_size,space_hardwareare likewise silently absorbed.@patch,Mock(), or simulations" — 60 of 240 test files use mocks, 2,513 occurrences, including 3 insidetests/real_world/.MIGRATION.mdis also wrong: it listsfrom clustrix import ClusterConfigunder "These imports continue to work unchanged" — that symbol is not inclustrix/__init__.pyat all. It also quotes atestpathsvalue and marker list that no longer matchpyproject.toml.Version drift — four locations, two values
clustrix/__init__.py:640.1.0docs/source/conf.py:170.1.0pyproject.toml:70.1.1setup.py:80.1.1Both
setup.pyandpyproject.tomldeclare name/version/deps independently. The PEP 517 build usespyproject.tomland silently ignoressetup.py, so the metadata you read may not be the metadata that installs.Docs site
docs/source/api/notebook_magic.rstautodocsClusterConfigWidget— no such class exists. The real ones areEnhancedClusterConfigWidget(notebook_magic_widget.py:35) andModernClustrixWidget(modern_notebook_widget.py:24).docs/source/index.rst:23lists only SLURM/PBS/SGE/Kubernetes/SSH — no cloud — contradicting the README's cloud claims.sphinx-buildfails atconf.py:34onModuleNotFoundError: No module named 'sphinx_wagtail_theme'(environment-only; RTD installs it).Acceptance criteria
README.mdis executed by a doc test in CI. This is the only durable fix — prose drifts, executed examples cannot.setup.py.MIGRATION.mdcorrected or retireddocs/autodoc targets resolve;index.rstandREADME.mdagree on the supported backend list