Thanks for the PR @reshamas but I don't think this is the right place for using the diagram rendering: this example is about a pipeline creation. Anything that's not directly related to that is noise and distracts from the original intent.

@NicolasHug Where is a good place to put it?
Referring to:

We probably need an example, or a user guide page, showing how different estimators are diagrammed, and perhaps also instructing users to use IPython.display's display function when needed.

I answered in the original issue ;)

That makes sense. Keep the conversation with the original issue.

(we need the :: otherwise this won't be interpreted as code)

@NicolasHug I accepted your suggestion and did "commit suggestion", but when I tried to push changes, I get:

▶ git push origin display-diagram 
To github.com:reshamas/scikit-learn.git
 ! [rejected]            display-diagram -> display-diagram (non-fast-forward)
error: failed to push some refs to 'git@github.com:reshamas/scikit-learn.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
(sklearndev) 

as suggested in the message, you need a git pull ;)

This happens because the branch on your fork (on the cloud) and the one on your local machine have diverged: they both got one commit that the other one doesn't

I tried both git pull and git pull upstream master. I also tried various permutations, and I am now "Lost in Git"

There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    git pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    git branch --set-upstream-to=<remote>/<branch> display-diagram

(sklearndev) 

the issue isn't with upstream master (which is this repo's main branch) but with this branch on your own fork: origin display-diagram

I'm a bit surprise git pull doesn't work, maybe try git pull origin display-diagram then?

Though it looks like you're on the sklearndev branch on your machine? (or is that the name of the virtualenv?)

ok, it went through. (the steps worked, but I needed to commit my changes first)

you have merge conflicts that weren't taken out of the file now

please use a :func: sphinx reference instead.

Also above we'll need an import for config_context.

When I run these lines in Jupyter:

import sklearn
from sklearn import set_config

with sklearn.config_context(display='diagram'):
    pipe

I don't get any output (no errors either).

ah, the context manager is such that the cell doesn't return the estimator. That's unfortunate, I wanted to avoid that all subsequent estimator would be rendered as diagrams but that won't be possible.

In this case, I would just remove the note and call set_config at the beginning of the pipeline section code blcok, with a short comment like:

set_config(display='diagram')  # for HTML repr of estimators

What if the code was replaced with what is below? This does render the diagram in Jupyter notebook.

from sklearn import set_config
set_config(display='diagram')

pipe

Sure, we can keep the note

This seems to create a rendering issue

@thomasjpfan any idea why this does not render as html?

This is pure rst, no code is actually ran when the docs are build. We have been linking to a sphinx gallery that properly displays the html repr.

Sidenote: I had a custom sphinx derivative that did just this, but I thought maintaining another sphinx derivative would be too much of a maintenance burden.

Should I move the example to another file?

Ah right, we do run the docs but not when building them :/

I think we should go with a dedicated example then, and not change the getting_started guide (#18305 (comment)). @reshamas I guess we can just merge this PR if you revert the changes made to getting_started.rst? Thanks and sorry for the extra work

No need for these

This doesn't render properly, I think you need to end the docstring before starting the # %% blocks

I am not sure that is the solution.
Example in this file: https://github.com/scikit-learn/scikit-learn/blob/master/examples/compose/plot_compare_reduction.py

When I end the docstring earlier, it doesn't work, unless I need two separate docstrings?

Note that the use of ``memory`` to enable caching becomes interesting when the
fitting of a transformer is costly.

# %%
Illustration of ``Pipeline`` and ``GridSearchCV``
###############################################################################

This section illustrates the use of a ``Pipeline`` with ``GridSearchCV``
"""

Hi @reshamas indeed you have found a bug in the documentation. You can see here the rendering of the page you referred to. The docstring needs to be ended there too. Would you be interested in proposing a pull request to fix the rendering of that page?

@cmarmo
Yes. @Mariam-ke and I try to meet weekly to work on a PR, so we'll continue work on this.

or call it "steps" instead of "estimators", since this is the name of the parameter.

+1 I think "steps" is a better name than "estimators". I made that update.