Build documentation on Read the Docs

[astrojuanlu]

Hi! This is a proposal to build the seaborn documentation on Read the Docs. Doing so has a bunch of interesting niceties, the best one for me being having the complete history of past seaborn versions (I've had to use Wayback Machine in the past to easily look for old documentation).

Full disclaimer: I work as Developer Advocate at Read the Docs, with a mission to help scientific projects improve their documentation, and I am more than happy to hear feedback or complaints!

This was proposed a while back, but the build process requires some tweaks to make it work properly on Read the Docs. To that end, this pull request contains three things:

• A proper .readthedocs.yaml configuration
• A hack to build the notebooks if an environment variable is detected
• A little hack to create the thumbnails directory before the actual build starts (see #2532)

The end result can be seen here: https://astrojuanlu-seaborn.readthedocs.io/en/rtd/

Although nowadays parts of the seaborn documentation workflow, and in particular tools/nb_to_doc.py, could be rewritten using something like nbsphinx (which I personally use in other projects to create example galleries based on Jupyter notebooks), I wanted to keep things as simple as possible.

@mwaskom What do you think?

cc @ericholscher

Edit: Simplified "hacks" after clarification, see discussion below

[codecov[bot]]

Codecov Report

Merging #2533 (ea2ea9e) into master (4f79753) will increase coverage by 0.18%. The diff coverage is n/a.

:exclamation: Current head ea2ea9e differs from pull request most recent head 5233a01. Consider uploading reports for the commit 5233a01 to get more accurate results

@@            Coverage Diff             @@
##           master    #2533      +/-   ##
==========================================
+ Coverage   97.27%   97.45%   +0.18%     
==========================================
  Files          17       17              
  Lines        6340     6325      -15     
==========================================
- Hits         6167     6164       -3     
+ Misses        173      161      -12     

Impacted Files	Coverage Δ
seaborn/axisgrid.py	95.62% <0.00%> (-0.04%)	:arrow_down:
seaborn/matrix.py	95.87% <0.00%> (ø)
seaborn/_statistics.py	100.00% <0.00%> (ø)
seaborn/categorical.py	98.54% <0.00%> (+0.14%)	:arrow_up:
seaborn/distributions.py	96.36% <0.00%> (+0.31%)	:arrow_up:
seaborn/regression.py	97.79% <0.00%> (+0.62%)	:arrow_up:
seaborn/_docstrings.py	100.00% <0.00%> (+12.50%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 4f79753...5233a01. Read the comment docs.

[mwaskom]

Glad you got it to work! However I'm not sure I find the argument for switching particularly compelling ...

If the main argument is archival versions, that is now basically solved. Are there other features I'm missing?

FWIW, last I looked into it, nbsphinx wasn't exactly a replacement for the way seaborn uses notebooks to write docs, though perhaps it's possible to fiddle with it to get what I want. But at this point, I'm the main and basically only person who needs to build the seaborn docs, and so I'm not thaaaat enthusiastic about replacing my workflow (which is arguably a sequences of hacks, but hacks that I know) with a new approach that I'd have to get accustomed to. It just seems like the time spent learning something new would be better spent on any of the other demands that already overwhelm the time I have to spent on seaborn.

But perhaps I'm missing something?

[mwaskom]

By the way, I guess I wasn't clear in my response to the other issue ... but I don't think you actually need to execute make html twice. Can't you just create the example_thumbs directory manually? (The fact that executing it twice works suggests that the right things are happening, but in the wrong order of operations. So it's a useful clue for fixing it, but not an ideal workaround).

[astrojuanlu]

You're right, it was as simple as having the directory before the build started! Just edited that part of the code.

But at this point, I'm the main and basically only person who needs to build the seaborn docs...

I totally agree with you, it makes little sense to change the build code for little gain.

If the main argument is archival versions, that is now basically solved. Are there other features I'm missing?

Nice, I hadn't seen the archive! There are other things you might find interesting:

• Since January this year, RTD allows you to easily preview the documentation from pull requests. This means that you can check in the PR itself how the docstrings look like, instead of waiting until release time to find those. It integrates nicely with the rest of the GitHub Actions checks, you have more info in the link.
• RTD taking care of the versioning means that you can have a development/master version of the documentation. While you probably want to still redirect https://seaborn.pydata.org/ to the latest released version, it can be useful to check out the current status of the development branch.
• All of this happens from the mkwaskom/seaborn repository, so you wouldn't need to push new versions to https://github.com/seaborn/seaborn.github.io/. In fact, every time you tag a new version, you would have its documentation online instantly.
• And speaking about domains and redirections, RTD also gives you user-defined redirects (for example, if you change the name of a tutorial but want old links to work), custom domains (similar to how GitHub pages is already configured), custom 404 pages (instead of the default GitHub pages one)... And much more 😁

[astrojuanlu]

Rebased and force-pushed on top of #2572.

[EwoutH]

What might be interesting, is that there now is a much used PyData Sphinx Theme. NumPy, Pandas, SciPy, NetworkX and many other projects use it.

So that would add a possibility to switch to Read the Docs while maintaining the same styling.

[mwaskom]

The concern was never about styling, just about workflow. I appreciate that RTD has some nice features that make collaborating on doc updates easier, but those just aren't particularly compelling for seaborn at this time. This PR is a useful POC and perhaps can be revisited in the future, but I think for now I've no appetite for moving away from an approach that currently satisfies all of my needs.