[v4.0] Make a bunch of updates to the docs. #1014

anoto-moniz · 2026-01-22T20:56:24Z

Some was made incorrect by the v4.0 release, but there was also a lot of old information that hasn't been corrct for some time. I corrected as much of it as I could find.

This deliberately omits a new section in the design space docs on hierarchical design spaces. That will be added separately, pre-release.

PR Type:

Breaking change (fix or feature that would cause existing functionality to change)
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Maintenance (non-breaking change to assist developers)

Adherence to team decisions

I have added tests for 100% coverage
I have written Numpy-style docstrings for every method and class.
I have communicated the downstream consequences of the PR to others.
I have bumped the version in __version__.py

anoto-moniz · 2026-01-23T18:54:01Z

docs/source/getting_started/basic_functionality.rst

 ---------------

-After registering an asset, the ``status`` command can be used to obtain a static readout of the state of the asset on the platform (e.g., VALID, INVALID, VALIDATING, SUCCEEDED, FAILED, INPROGRESS). 
+After registering an asset, the ``status`` command can be used to obtain a static readout of the state of the asset on the platform (e.g., READY, INVALID, VALIDATING, SUCCEEDED, FAILED, INPROGRESS). 


Ironically, VALID is not a valid state

Not today, but I've created enumerated lists for these status fields in mock-client. We might want to just incorporate them into the main library.

anoto-moniz · 2026-01-23T18:54:57Z

docs/source/getting_started/projects.rst

-    if project.name == project_name), None)
+    project = next((project for project in all_projects if project.name == project_name), None)
+
+or use the :func:`~citrine.seeding.find_or_create.find_or_create_project` convenience method:


Was there a reason we previously didn't mention find_or_create_project? Or was this just written before it was created?

Probably just legacy. Good add.

anoto-moniz · 2026-01-23T18:55:48Z

docs/source/workflows/design_spaces.rst

+Hierarchical Design Space
+-------------------------
+


This is intentionally left blank for now. @jspeerless has offered to put together this section before release.

anoto-moniz · 2026-01-23T18:56:48Z

docs/source/workflows/design_spaces.rst

Wrapping design spaces in ProductDesignSpace, dropping references to EnumeratedDesignSpace, and mentioning that DataSourceDesignSpace and FormulationDesignSpace must be part of a ProductDesignSpace.

anoto-moniz · 2026-01-23T18:59:59Z

docs/source/workflows/getting_started.rst

 Validation status can be one of the following states:

-  **Created:** The module/workflow has been registered with a project and has been queued for validation.
+-  **Created:** The module/workflow has been registered with a project, but validation has not begun.


Although the SDK automatically starts validation, the UI does not. Also, in the SDK, you can prevent automatically training a predictor when registering or updating with train=False.

anoto-moniz · 2026-01-23T19:03:41Z

docs/source/workflows/predictors.rst

Dehydrated predictors are no longer supported. Subpredictor training_data is hoisted up to the graph predictor in the backend; by disallowing it in the SDK, we can finally get rid of that code. And all the examples should register only GraphPredictor.

kroenlein

Deltas look good, but it probably warrants a detailed reread by Product before release. As I think it planned.

kroenlein · 2026-01-29T17:26:47Z

docs/source/FAQ/predictor_evaluation_migration.rst

 =======

-In version 4.0, :py:class:`Predictor Evaluation Workflows <citrine.resources.predictor_evaluation_workflow.PredictorEvaluationWorkflowCollection>` and :py:class:`Predictor Evaluation Executions <citrine.resources.predictor_evaluation_execution.PredictorEvaluationExecutionCollection>` (collectively, PEWs) will be merged into a single entity called :py:class:`Predictor Evaluations  <citrine.resources.predictor_evaluation.PredictorEvaluationCollection>`. The new entity will retain the functionality of its predecessors, while simplyfing interactions with it. And it will support the continuing evolution of the platform.
+`Predictor Evaluation Workflows` and `Predictor Evaluation Executions` (collectively, PEWs) have been merged into a single entity called :py:class:`Predictor Evaluations <citrine.resources.predictor_evaluation.PredictorEvaluationCollection>`. The new entity retains the functionality of its predecessors, while simplyfing interactions with it. And it will support the continuing evolution of the platform.


Suggested change

`Predictor Evaluation Workflows` and `Predictor Evaluation Executions` (collectively, PEWs) have been merged into a single entity called :py:class:`Predictor Evaluations <citrine.resources.predictor_evaluation.PredictorEvaluationCollection>`. The new entity retains the functionality of its predecessors, while simplyfing interactions with it. And it will support the continuing evolution of the platform.

`Predictor Evaluation Workflows` and `Predictor Evaluation Executions` (collectively, PEWs) have been merged into a single entity called :py:class:`Predictor Evaluations <citrine.resources.predictor_evaluation.PredictorEvaluationCollection>`. The new entity retains the functionality of its predecessors, while simplyfing interactions with it, while supporting the continuing evolution of the platform.

Personal issue with starting a sentence with an And.

kroenlein · 2026-01-29T17:27:45Z

docs/source/getting_started/basic_functionality.rst

 ---------------

-After registering an asset, the ``status`` command can be used to obtain a static readout of the state of the asset on the platform (e.g., VALID, INVALID, VALIDATING, SUCCEEDED, FAILED, INPROGRESS). 
+After registering an asset, the ``status`` command can be used to obtain a static readout of the state of the asset on the platform (e.g., READY, INVALID, VALIDATING, SUCCEEDED, FAILED, INPROGRESS). 


Not today, but I've created enumerated lists for these status fields in mock-client. We might want to just incorporate them into the main library.

kroenlein · 2026-01-29T17:30:21Z

docs/source/getting_started/projects.rst

-    if project.name == project_name), None)
+    project = next((project for project in all_projects if project.name == project_name), None)
+
+or use the :func:`~citrine.seeding.find_or_create.find_or_create_project` convenience method:


Probably just legacy. Good add.

Some was made incorrect by the v4.0 release, but there was also a lot of old information that hasn't been corrct for some time. I corrected as much of it as I could find. This deliberately omits a new section in the design space docs on hierarchical design spaces. That will be added separately, pre-release.

anoto-moniz commented Jan 23, 2026

View reviewed changes

anoto-moniz marked this pull request as ready for review January 23, 2026 19:04

anoto-moniz requested a review from a team as a code owner January 23, 2026 19:04

kroenlein approved these changes Jan 29, 2026

View reviewed changes

anoto-moniz force-pushed the feature/update-docs branch from 029a7b8 to 865ca6a Compare January 29, 2026 17:44

anoto-moniz merged commit 0418ae4 into release/v4.0 Jan 29, 2026
41 checks passed

anoto-moniz deleted the feature/update-docs branch January 29, 2026 17:44

		Hierarchical Design Space
		-------------------------

[v4.0] Make a bunch of updates to the docs. #1014

[v4.0] Make a bunch of updates to the docs. #1014

Uh oh!

Conversation

anoto-moniz commented Jan 22, 2026

PR Type:

Adherence to team decisions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kroenlein left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants