Guidance on documentation

[Conengmo]

There is documentation and examples in multiple places:

• There is the docs folder, which is build and shown on github.io. It contain an installation guide, quick start examples and the API documentation.
• Then there is the examples folder, which is best viewed online with Jupyter nbviewer.
• And there is a folium_contrib repository, which contains a few user contributed examples. These are also best viewed with Jupyter nbviewer

@ocefpaf can you share your plan for the structure of the documentation? I can spend some time on this, but I want to do it right :)

[ocefpaf]

@ocefpaf can you share your plan for the structure of the documentation?

To be honest I don't have a clear plan 😬

I can spend some time on this, but I want to do it right :)

That would be awesome!

Right now examples is a mixture of tests and demos I would like to disambiguate that.
Here is what I wanted to do some time ago:

• move most of the notebooks in the example folder to python-visualization/folium_contrib
• create a gallery webpage there, with the same infrastructure from python-visualization/folium, so we can either link to the HTML pages or to nbviewer
• adapt some key notebooks from examples to be tests and renamed that folder to make it "invisible" to users (users should use the gallery as examples and not the tests)

I am not sure you want to tackle that, it is kind of boring and it would demand some knowledge of which notebook we need as test and which we don't. Maybe a review of the current docs would be less boring?

[Conengmo]

Thanks for explaining! I'll stay out of the examples then and look into the 'regular' documentation.

By the way, maybe it's a good idea to put the links to both of the nbviewer pages in the readme. Until you've created the full folium_contrib webpage. I know when I started using Folium it took me a while to sort out what was where, so it might help new users.

[ocefpaf]

By the way, maybe it's a good idea to put the links to both of the nbviewer pages in the readme.

Yep. We should do that!

[AlJohri]

hi, just wanted to note that it seems the docs website is more recent than the latest stable version. just got stuck trying to use toolip= with Marker as per the docs. I installed from git to get around this for now. thanks!

[ocefpaf]

@AlJohri you are correct. The docs are versioned and we should advertise the latest releases version.

See http://python-visualization.github.io/folium/docs-v0.5.0/