Merge pull request #83 from jklymak/doc-move-to-sphinx

DOC: move to sphinx

Author: tacaswell

.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

docs/index.rst

@@ -1,17 +1,25 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.9
 # To update, run:
 #
 #    pip-compile requirements.in
 #
 --no-binary shapely
 
+alabaster==0.7.12
+    # via sphinx
 appdirs==1.4.4
     # via virtualenv
+babel==2.9.1
+    # via sphinx
+beautifulsoup4==4.10.0
+    # via pydata-sphinx-theme
 bump2version==1.0.1
     # via -r requirements.in
 cartopy==0.19.0.post1
     # via -r requirements.in
+certifi==2021.10.8
+    # via requests
 cffi==1.15.0
     # via cryptography
 cfgv==3.2.0
@@ -20,6 +28,8 @@ chardet==4.0.0
     # via
     #   pdfminer.six
     #   pdfx
+charset-normalizer==2.0.7
+    # via requests
 click==8.0.0
     # via pip-tools
 cryptography==35.0.0
@@ -28,26 +38,37 @@ cycler==0.10.0
     # via matplotlib
 distlib==0.3.1
     # via virtualenv
+docutils==0.17.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
 filelock==3.0.12
     # via virtualenv
 identify==2.2.2
     # via pre-commit
-importlib-metadata==3.9.0
-    # via
-    #   pep517
-    #   pre-commit
-    #   virtualenv
+idna==3.3
+    # via requests
+imagesize==1.2.0
+    # via sphinx
+jinja2==3.0.2
+    # via sphinx
 kiwisolver==1.3.1
     # via matplotlib
+markupsafe==2.0.1
+    # via jinja2
 matplotlib==3.4.2
     # via -r requirements.in
+mpl-sphinx-theme==0.0.6
+    # via -r requirements.in
 nodeenv==1.5.0
     # via pre-commit
 numpy==1.19.5
     # via
     #   cartopy
     #   matplotlib
     #   scipy
+packaging==21.2
+    # via sphinx
 pdfminer.six==20201018
     # via pdfx
 pdfx==1.4.1
@@ -62,14 +83,24 @@ pre-commit==2.11.1
     # via -r requirements.in
 pycparser==2.20
     # via cffi
+pydata-sphinx-theme==0.7.1
+    # via mpl-sphinx-theme
+pygments==2.10.0
+    # via sphinx
 pyparsing==2.4.7
-    # via matplotlib
+    # via
+    #   matplotlib
+    #   packaging
 pyshp==2.1.3
     # via cartopy
 python-dateutil==2.8.1
     # via matplotlib
+pytz==2021.3
+    # via babel
 pyyaml==5.4.1
     # via pre-commit
+requests==2.26.0
+    # via sphinx
 scipy==1.5.4
     # via -r requirements.in
 shapely==1.7.1
@@ -79,20 +110,37 @@ six==1.15.0
     #   cycler
     #   python-dateutil
     #   virtualenv
+snowballstemmer==2.1.0
+    # via sphinx
 sortedcontainers==2.4.0
     # via pdfminer.six
+soupsieve==2.3
+    # via beautifulsoup4
+sphinx==4.2.0
+    # via
+    #   -r requirements.in
+    #   pydata-sphinx-theme
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
 toml==0.10.2
     # via
     #   pep517
     #   pre-commit
-typing-extensions==3.7.4.3
-    # via importlib-metadata
+urllib3==1.26.7
+    # via requests
 virtualenv==20.4.3
     # via pre-commit
-zipp==3.4.1
-    # via
-    #   importlib-metadata
-    #   pep517
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip
+# setuptools