Documentation overhaul

[Conengmo]

I'm preparing a documentation overhaul.

First some issues I see with our current documentation:

• Very limited usage guides, mostly API reference.
• Reliance on example notebooks:
  • In which features are not easily discoverable. A user has to browse them by file name.
  • Hosted on nbviewer.org, not integrated in our documentation.
• I don't like the theme:
  • In the API reference it looks like a wall of text without clear breaks between classes.
  • The font is small, the look and feel is outdated.
  • The content guide on the right side is not easy to use.
• A lot of user questions are answered in the Github Issues. That means a user has to search to our issues to find answers to questions that are not in the documentation.

Improvements

• Use a modern theme.
• Well structured, easy to navigate.
• Add a comprehensive usage guide.
• Include more advanced examples in the documentation, without having to go to nbviewer.org.
• Include answers to questions asked in Issues, keep updating that.

Documentation parts

• Getting started. Installation, first example.
• Usage guide. This is the most high-level, aims to show users all the core features and plugins folium has.
• Advanced examples. Longer code snippets that show more advanced usage, like overwriting stuff or injecting custom JS.
• API reference.
• Ecosystem. Other packages that use folium. Move this part from the readme.
• Changelog. Render from CHANGES.txt.

Inspiration:

• https://altair-viz.github.io/index.html
• https://geopandas.org/en/stable/docs.html

Non-goals

• Make the documentation versioned.
• Include Jupyter Lite. I think it's very interesting technology, but:
  • First I'd like to focus on making great basic documentation.
  • It's still in beta.
  • Let's see how others adopt it first.

Approach

Theme

I propose using the WriteTheDocs theme: https://www.writethedocs.org/guide/tools/sphinx-themes/#read-the-docs-theme. I think it looks good. We can pull the repo, not having to include it ourselves.

Code

I've looked into this a little bit: https://docs.readthedocs.io/en/stable/guides/jupyter.html#using-notebooks-in-other-formats

I'm thinking to use MyST Markdown in our documentation. This works well for version control. And Sphinx can automatically execute it and include html output in our docs. I tested that and it works great.

During this project I'll use Jupytext to convert our existing notebooks to MyST Markdown. For example jupytext --to md:myst Quickstart.ipynb.

Existing example notebooks

Technically, these can be deprecated afterwards. The problem is that they have a lot of incoming links. So I suggest we keep them so we don't break stuff for incoming users. But in each one include a link to our proper documentation.

Automated notebook tests

Currently we run Selenium tests on our example notebooks, checking whether they run without issue. I would like to do something similar on the code we include in our documentation. Since the documentation should touch most, if not all of our code, it's a great place to test to avoid regressions.

We can use Jupytext to convert the Myst Markdown to a regular notebook, then use our existing pipeline.

Comments?

Let me know if you have ideas or comments!

[Conengmo]

@ocefpaf would you like to comment on this plan? If you’re busy I understand. I’ll gradually continue with this project, but it won’t happen overnight.

[ocefpaf]

It is a nice plan. I wonder if we should ask for help on this. We may apply for GSoC 23 and mentor someone, if you are interested,

[Conengmo]

Thanks for your comment! I'll continue with the plan.

We may apply for GSoC 23 and mentor someone

Interesting idea. I hope to have finished the documentation by then though. But we can think about some projects we might put out. There are some interesting ideas still in our issue list that someone might pick up. I'll open a new issue later to discuss this and collect ideas.

[martinfleis]

I like these plans!

I just have to admit that I am not a big fan of the readthedocs theme as it's not very modern. This is how it looks on a 4k monitor

I would consider some that are more recent than the rtd one, like pydata (used by geopandas linked above), book (xarray for example), furo.

+1 for MyST

The problem is that they have a lot of incoming links. So I suggest we keep them so we don't break stuff for incoming users. But in each one include a link to our proper documentation.

We can do automatic redirection to a new place. See how it is done in geopandas - https://github.com/geopandas/geopandas/blob/main/doc/source/conf.py#L433. Otherwise it would have to stay in the TOC for sphinx to generate it.

[Conengmo]

Thanks for your comment Martin! Much appreciated.

I'll take your advice on the template and try one of the ones you mentioned, probably pydata, which does look very good.

I do like how you link to source in the geopandas documentation. I'm not sure if that would help in the case of our example notebooks. The links in the wild point to nbviewer.org, which we don't really have control over.

I'll take a good look at the way geopandas configured their documentation and try to copy some stuff from there :)

[martinfleis]

If you have questions about geopadnas docs shoot them my way. I was responsible for the overhaul there.

[mikedbjones]

In the meantime, while the documentation is being overhauled, is the current documentation still online? I can't find it at https://python-visualization.github.io/folium/. Thanks.

[martinfleis]

@mikedbjones I can see it on the link you posted. What do you see there?

[mikedbjones]

Interesting, thanks for the reply, I'm getting some kind of SSL issue in both Chrome and Firefox. Maybe an issue on my end?

[martinfleis]

@mikedbjones I am not able to reproduce that in neither Safari, Chrome, Arc or Firefox. So might be on your side? Not sure.

[Conengmo]

To do:

• Update Readme
  • Remove links to example notebooks
  • Link to latest docs
  • Update logo url
• Point our example notebooks to the new documentation
• Add link to Github repo to doc header
• (Add transparent png logo, also to header)

[Conengmo]

It's pretty much done, so I'm going to close this ticket. I'm happy with the result :) Thanks for your input Martin!