User guide LayerControl example (controlling TileLayer) doesn't work

[elliot-100]

Describe the bug
At https://python-visualization.github.io/folium/latest/user_guide/ui_elements/layer_control.html, the text says 'add a control to the map to show or hide layers'. But the demo (or local HTML produced by equivalent code on my machine) seems to have incorrect code, which adds the control but has no effect on the TileLayer.

To Reproduce / Expected behavior

• View demo at https://python-visualization.github.io/folium/latest/user_guide/ui_elements/layer_control.html
• Initially the 'openstreetmap' control isn't selected (as expected), but OpenStreet map tiles are visible (expected not visible)
• The 'openstreetmap' control can be selected with no effect, but not deselected.

Environment (please complete the following information):

• Browser: Chrome or Edge
• Jupyter Notebook or html files? User guide uses Notebook; local env: HTML
• Python version: local env: sys.version_info(major=3, minor=12, micro=5, releaselevel='final', serial=0)
• folium version: local env: 0.19.4
• branca version: local env 0.8.1

Additional context/Possible solutions
If I change this in my local env:

folium.TileLayer("OpenStreetMap").add_to(m)
folium.TileLayer(show=False).add_to(m)

To:

folium.TileLayer("OpenStreetMap", show=False).add_to(m)

This partially fixes the problem - the OpenStreet map tiles are not initially visible, and the 'openstreetmap' control can be selected to make them visible, however the control cannot be deselected and so the tiles cannot be hidden again.

[Edit: I have only encountered this with a TileLayer - no issues controlling a FeatureGroup with a LayerControl]

folium is maintained by volunteers. Can you help making a fix for this issue?
Maybe, depending on complex the docs setup is; need to understand root issue first.

[elliot-100]

From experimentation (and reading the rest of the page...) the problem is that TileLayers are base layers by default, so mutually exclusive.

So the example:

m = folium.Map(tiles=None)

folium.TileLayer("OpenStreetMap").add_to(m)
folium.TileLayer(show=False).add_to(m)

folium.LayerControl().add_to(m)

m

Should be [corrected]:

m = folium.Map(tiles=None)

folium.TileLayer("OpenStreetMap", overlay=True).add_to(m)

folium.LayerControl().add_to(m)

m

So it does what it describes "add a control to the map to show or hide layers".

I don't think the show=False should be in there, as the 3rd example 'Show manually' covers that behaviour.

[elliot-100]

Raised PR #2105.

[hansthen]

You are right. The documentation about Layers is confusing. I also ran into this when I first started out with Folium. Let me have a look at your PR over the weekend. I have not have had time to take a detailed look at the other issues you created, but I will block some time this weekend.

[elliot-100]

On looking at this specific issue again, what I've written above doesn't make logical sense - I think I may be getting inconsistent/unexpected/buggy behaviour in my environment.

I will try to put a set of test cases together so it's clear to me how things actually behave, and will make the PR draft.

[Edit: resolved, simple copy/paste error on my part]