DOC: switch to sphinx

Author: jklymak

.circleci/config.yml

@@ -0,0 +1,24 @@
+version: 2.1
+
+orbs:
+  python: circleci/[email protected]
+
+jobs:
+  build_docs:
+    executor: python/default
+    steps:
+      - checkout
+      - python/install-deps
+      - run:
+          name: Build cheatsheets and docs
+          command: make all
+      - persist_to_workspace:
+          root: docs/_build/html
+          paths: .
+      - store_artifacts:
+          path: docs/_build/html/
+
+workflows:
+  main:
+    jobs:
+      - build_docs

.github/workflows/main.yaml

@@ -61,10 +61,11 @@ jobs:
           path: |
             cheatsheets.pdf
             handout-*.pdf
+            ./docs/_build/html/
       - name: Publish cheatsheets and handouts
         if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./build/
+          publish_dir: ./docs/_build/html/
           force_orphan: true

.gitignore

@@ -16,3 +16,9 @@ handout-*.png
 # ----------------------------------
 figures/*.pdf
 fonts/**/*.[ot]tf
+
+# html build
+docs/_build/*
+
+# OS specific
+.DS_Store

Makefile

@@ -4,10 +4,7 @@ SRC := $(wildcard *.tex)
 default: all
 
 .PHONY: all
-all: logos figures cheatsheets handouts
-	mkdir -p ./build/
-	cp cheatsheets*.p* ./build/
-	cp handout-*.p* ./build/
+all: logos figures cheatsheets handouts docs
 
 .PHONY: logos
 logos:
@@ -16,11 +13,11 @@ logos:
 .PHONY: figures
 figures:
 	# generate the figures
-	cd scripts && for script in *.py; do echo $$script; python $$script; done
+	cd scripts && for script in *.py; do echo $$script; MPLBACKEND="agg" python $$script; done
 	# crop the figures
 	cd figures && for figure in *.pdf; do echo $$figure; pdfcrop $$figure $$figure; done
 	# regenerate some figures that should not be cropped
-	cd scripts && python styles.py
+	cd scripts && MPLBACKEND="agg" python styles.py
 
 .PHONY: cheatsheets
 cheatsheets:
@@ -44,6 +41,13 @@ check:
 	./check-num-pages.sh handout-intermediate.pdf 1
 	./check-links.py cheatsheets.pdf
 
+.PHONY: docs
+docs:
+	make -C docs/ html
+	cp ./cheatsheets*.p* ./docs/_build/html
+	cp ./handout-*.p* ./docs/_build/html
+
+
 .PHONY: fonts
 fonts:
 	make -C fonts/

build/index.html

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+show:
+	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(shell pwd)/build/html/index.html')"
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,41 @@
+import datetime
+
+# -- Project information -----------------------------------------------------
+
+html_title = 'Visualization with Python'
+project = "Matplotlib cheatsheets"
+copyright = (
+     f"2012 - {datetime.datetime.now().year} The Matplotlib development team"
+ )
+author = "Matplotlib Developers"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+
+templates_path = []
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+html_css_files = ['css/normalize.css', 'css/landing.css']
+html_theme = "mpl_sphinx_theme"
+html_favicon = "_static/favicon.ico"
+html_theme_options = {
+    "logo_link": "https://matplotlib.org/stable/",
+    "native_site": False,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the theme static files,
+# so a file named "default.css" will overwrite the theme's "default.css".
+html_static_path = ["_static"]

docs/_static/favicon.ico

@@ -0,0 +1,65 @@
+.. title:: Matplotlib cheatsheets
+
+***********************************
+Matplotlib cheatsheets and handouts
+***********************************
+
+Cheatsheets
+***********
+
+.. container:: twocol
+
+    .. container::
+
+      .. image:: ../cheatsheets-1.png
+         :width: 270px
+         :align: center
+         :alt: image of first page of cheatsheets
+
+
+    .. container::
+
+      .. image:: ../cheatsheets-2.png
+         :width: 270px
+         :align: center
+         :alt: image of second page of cheatsheets
+         
+
+`Cheatsheets [pdf] <./cheatsheets.pdf>`_
+
+
+
+Handouts
+********
+
+.. container:: twocol
+
+   .. container::
+
+      .. image:: ../handout-beginner.png
+         :width: 270px
+         :align: center
+         :alt: image of beginner handout
+
+      `Beginner [pdf] <./handout-beginner.pdf>`_
+
+
+   .. container::
+
+      .. image:: ../handout-intermediate.png
+         :width: 270px
+         :align: center
+         :alt: image of intermediate handout
+
+      `Intermediate [pdf] <./handout-intermediate.pdf>`_
+
+
+   .. container::
+
+      .. image:: ../handout-tips.png
+         :width: 270px
+         :align: center
+         :alt: image of tips handout
+
+      `Tips [pdf] <./handout-tips.pdf>`_
+

docs/conf.py

@@ -5,5 +5,7 @@ pdfx
 pip-tools
 pre-commit
 scipy
+sphinx
+mpl-sphinx-theme
 
 --no-binary shapely