Store code examples in API docs using notebooks (#2123)

* Add new infrastructure for generating docs from notebooks

* Move rugplot examples into notebook

* More imporvements to new notebook processing infrastructure

* Add output stripping to doc notebook build

* Add script for auto-generating API doc notebooks

* Improve Makefile infra

* Convert kdeplot API docs to notebook

* Read notebook kernel from environment variable

* Add pandoc to GH doc build

* Consolidate workflow

.github/workflows/ci.yaml

@@ -30,7 +30,7 @@ jobs:
       - name: Install doc tools
         run: |
           pip install -r doc/requirements.txt
+          sudo apt-get install pandoc
 
       - name: Build docs
-        run: |
-          make -C doc notebooks html
+        run: make -C doc notebooks html

doc/.gitignore

@@ -4,13 +4,5 @@ generated/
 examples/
 example_thumbs/
 introduction.rst
-aesthetics.rst
-relational.rst
-color_palettes.rst
-distributions.rst
-regression.rst
-categorical.rst
-plotting_distributions.rst
-dataset_exploration.rst
-timeseries_plots.rst
-axis_grids.rst
+tutorial/*.rst
+docstrings/*.rst

doc/Makefile

@@ -46,17 +46,24 @@ clean:
 	-rm -rf example_thumbs/*
 	-rm -rf tutorial/*_files/
 	-rm -rf tutorial/*.rst
+	-rm -rf docstrings/*_files/
+	-rm -rf docstrings/*.rst
 	-rm -rf generated/*
 	-rm -rf introduction_files/*
 	-rm introduction.rst
 
+.PHONY: tutorials
 tutorials:
 	make -C tutorial
 
-introduction: introduction.ipynb
-	tools/nb_to_doc.py introduction
+.PHONY: docstrings
+docstrings:
+	make -C docstrings
 
-notebooks: tutorials introduction
+introduction.rst: introduction.ipynb
+	tools/nb_to_doc.py ./introduction.ipynb
+
+notebooks: tutorials docstrings introduction.rst
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

doc/docstrings/Makefile

@@ -0,0 +1,10 @@
+rst_files := $(patsubst %.ipynb,%.rst,$(wildcard *.ipynb))
+
+docstrings: ${rst_files}
+
+%.rst: %.ipynb
+	@../tools/nb_to_doc.py $*.ipynb
+	@cp -r $*_files ../generated/
+	@if [ -f ../generated/seaborn.$*.rst ]; then \
+	    touch ../generated/seaborn.$*.rst; \
+	 fi