Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add flowchart to explains the difference of bootstrap_project and configure_project #3470

Merged
merged 9 commits into from
Jan 9, 2024
1 change: 1 addition & 0 deletions RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
* Added logging about not using async mode in `SequentiallRunner` and `ParallelRunner`.

## Documentation changes
* Added documentations about `bootstrap_project` and `configure_project`.

## Community contributions

Expand Down
29 changes: 28 additions & 1 deletion docs/source/kedro_project_setup/session.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,31 @@
- `save_on_close`: A boolean value to indicate whether or not to save the session to disk when it's closed
- `env`: Environment for the `KedroContext`
- `extra_params`: Optional dictionary containing extra project parameters
for the underlying `KedroContext`; if specified, this will update (and therefore take precedence over) parameters retrieved from the project configuration
for the underlying **`KedroContext`**; if specified, this will update (and therefore take precedence over) parameters retrieved from the project configuration

Check warning on line 39 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L39

[Kedro.toowordy] 'therefore' is too wordy
Raw output
{"message": "[Kedro.toowordy] 'therefore' is too wordy", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 39, "column": 76}}}, "severity": "WARNING"}

## `bootstrap_project` and `configure_project`
```{image} ../meta/images/kedro-session-creation.png
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason for using this style of image rather than the ! []() markdown notation? Reason I ask is that it doesn't render on GitHub and I think it would help our readers to have visibility on the graphic here if possible (and you can add alt tags if you want them, so no need to use the rst image syntax -- AFAICT?).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

very good question! I don't have a good idea, it appears to me @astrojuanlu did something to all mermaid diagram with this new style. I also found it annoying it won't render in VSCode.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Block-level images aren't really needed https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#block-level-images I kept them for consistency, they can be turned into inline images

:alt: mermaid-General overview diagram for KedroSession creation
```

% Mermaid code, see https://github.com/kedro-org/kedro/wiki/Render-Mermaid-diagrams

Check notice on line 46 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L46

[Kedro.sentencelength] Try to keep your sentence length to 30 words or fewer.
Raw output
{"message": "[Kedro.sentencelength] Try to keep your sentence length to 30 words or fewer.", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 46, "column": 3}}}, "severity": "INFO"}
% graph LR
% subgraph Kedro Startup Flowchart

Check warning on line 48 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L48

[Kedro.Spellings] Did you really mean 'subgraph'?
Raw output
{"message": "[Kedro.Spellings] Did you really mean 'subgraph'?", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 48, "column": 4}}}, "severity": "WARNING"}
% A[bootstrap_project] -->|Read pyproject.toml| B
% A -->|Add project root to sys.path| B[configure_project]
% C[Initialize KedroSession]

Check warning on line 51 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L51

[Kedro.ukspelling] In general, use UK English spelling instead of 'Initialize'.
Raw output
{"message": "[Kedro.ukspelling] In general, use UK English spelling instead of 'Initialize'.", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 51, "column": 8}}}, "severity": "WARNING"}
% B --> |Read settings.py| C
% B --> |Read pipeline_registry.py| C
% end

Both `bootstrap_project` and `configure_project` handle the setup of a Kedro project, but there are subtle differences: `bootstrap_project` is used for project mode, and `configure_project` is used for packaged mode.

Kedro's CLI runs the functions at startup as part of `kedro run` so in most cases you don't need to call these functions. If you want to [interact with a Kedro project programatically in an interactive session such as Notebook](../notebooks_and_ipython/kedro_and_notebooks.md#reload_kedro-line-magic), use `%reload_kedro` line magic with Jupyter or IPython. Only use these functions directly if none of these methods work.

Check warning on line 58 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L58

[Kedro.Spellings] Did you really mean 'programatically'?
Raw output
{"message": "[Kedro.Spellings] Did you really mean 'programatically'?", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 58, "column": 169}}}, "severity": "WARNING"}

Check warning on line 58 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L58

[Kedro.weaselwords] 'Only' is a weasel word!
Raw output
{"message": "[Kedro.weaselwords] 'Only' is a weasel word!", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 58, "column": 359}}}, "severity": "WARNING"}

### `bootstrap_project`

This function uses `configure_project` under the hood, and additionally reads metadata from `pyproject.toml` and adds the project root to `sys.path` so the project can be imported as a Python package. It is typically used to work directly with the source code of a Kedro project.

Check warning on line 62 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L62

[Kedro.words] Use '' instead of 'under the hood'.
Raw output
{"message": "[Kedro.words] Use '' instead of 'under the hood'.", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 62, "column": 40}}}, "severity": "WARNING"}

Check warning on line 62 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L62

[Kedro.weaselwords] 'additionally' is a weasel word!
Raw output
{"message": "[Kedro.weaselwords] 'additionally' is a weasel word!", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 62, "column": 60}}}, "severity": "WARNING"}

### `configure_project`

This function reads `settings.py` and `pipeline_registry.py` and registers the configuration before Kedro's run starts. If you have a packaged Kedro project, you only need to run `configure_project` before executing your pipeline.

Check warning on line 66 in docs/source/kedro_project_setup/session.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/source/kedro_project_setup/session.md#L66

[Kedro.weaselwords] 'only' is a weasel word!
Raw output
{"message": "[Kedro.weaselwords] 'only' is a weasel word!", "location": {"path": "docs/source/kedro_project_setup/session.md", "range": {"start": {"line": 66, "column": 163}}}, "severity": "WARNING"}
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.