Quarto Doc

.github/workflows/documentation.yml

@@ -0,0 +1,54 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main", "dev", "doc", "qdoc", "dev-*"]
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: [3.11]
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: "1.4.521"
+
+      - name: Install Package
+        run: |
+          pip install git+https://github.com/has2k1/mizani.git@main
+          python -m pip install ".[doc]"
+          pip install -r requirements/doc.txt
+          quarto add --no-prompt has2k1/issuey
+
+      - name: Environment Information
+        shell: bash
+        run: |
+          ls -la
+          ls -la doc
+          pip list
+
+      - name: Build docs
+        run: |
+          make doc
+
+      - name: Deploy to Github Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: doc/_site

.github/workflows/testing.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [3.9, 3.11]
+        python-version: [3.9, 3.12]
 
     steps:
       - name: Checkout Code
@@ -144,21 +144,24 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: "1.4.521"
+
       - name: Install Packages
         shell: bash
         run: |
           sudo apt-get install pandoc
           pip install git+https://github.com/has2k1/mizani.git@main
           pip install ".[test,doc]"
-          pip install -r requirements/examples.txt
+          pip install -r requirements/doc.txt
+          quarto add --no-prompt has2k1/issuey
 
       - name: Environment Information
         shell: bash
         run: pip list
 
-      - name: Build Documentation
-        shell: bash
+      - name: Build documentation
         run: |
-          pushd doc
-          SPHINXOPTS=-W
-          make html && popd
+          make doc

.gitignore

@@ -60,6 +60,10 @@ tests/result_images/
 notes.txt
 examples/.ipynb_checkpoints
 
+# plotnine developing
+.ipynb_checkpoints/
+*.ipynb
+
 # Translations
 *.mo
 *.pot
@@ -85,3 +89,17 @@ benchmarks
 
 # version file generated by setuptools-scm
 plotnine/_version.py
+
+
+# Documentation
+doc/plotnine_examples/
+doc/reference/
+doc/_site/
+doc/_inv/
+doc/_extensions/
+doc/.quarto/
+doc/gallery/thumbnails
+doc/objects.json
+doc/objects.txt
+doc/.luarc.json
+doc/_environment

Makefile

@@ -69,9 +69,10 @@ coverage:
 	$(BROWSER) htmlcov/index.html
 
 doc:
-	$(MAKE) -C doc clean
-	$(MAKE) -C doc html
-	$(BROWSER) doc/_build/html/index.html
+	$(MAKE) -C doc doc
+
+doc-preview:
+	$(MAKE) -C doc preview
 
 release: clean
 	bash ./tools/release.sh

doc/.gitignore

@@ -0,0 +1 @@
+/.quarto/

doc/Makefile

@@ -1,60 +1,13 @@
-# Makefile for Sphinx documentation
-#
+interlinks:
+	quartodoc interlinks
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = plotnine
-SOURCEDIR     = .
-PAPER         =
-BUILDDIR      = _build
+build:
+	quartodoc build
 
-# For make theme
-BOOTSWATCHTHEME = united
-brand-primary = \#9E2F68
-headings-font-weight = bold
-font-family-sans-serif = '"system-ui", "Segoe UI", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"'
+render: build
+	quarto render
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "  theme    to create a custom sphinx boostrap theme"
-	@echo "  logo     to generate logo images"
-	@echo "  readme_images to generate images used in README.rst"
+doc: interlinks render
 
-.PHONY: help Makefile theme logo readme_images
-
-# 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)
-
-theme:
-	../tools/build_theme.sh --theme $(BOOTSWATCHTHEME) \
-	   --brand-primary '$(brand-primary)' \
-	   --headings-font-weight $(headings-font-weight) \
-	   --font-family-sans-serif '$(font-family-sans-serif)'
-
-logo:
-	cd images; \
-	python logo.py; \
-	convert -trim -density 300 -alpha remove -background '#FFFFFF' \
-	   -gravity center -scale 528x528 -extent 540x540 \
-	   -border 6 -bordercolor '#441A3F'\
-	   logo.pdf logo-540.png; \
-	convert -trim -density 300 -alpha remove -background '#FFFFFF' \
-	   -gravity center -scale 176x176 -extent 180x180 \
-	   -border 2 -bordercolor '#441A3F'\
-	   logo.pdf logo-180.png; \
-	convert -trim -density 300 -alpha remove -background '#FFFFFF' \
-	   -gravity center -scale 32x32 \
-	   -border 2 -bordercolor '#441A3F'\
-	   logo-small.pdf logo-32.png; \
-	convert -trim -density 300 -alpha remove -background '#FFFFFF' \
-	   -gravity center -scale 32x32 \
-	   -border 2 -bordercolor '#441A3F'\
-	   logo-small.pdf favicon.ico;
-
-readme_images:
-	cd images; \
-	python readme_images.py
+preview:
+	quarto preview --port 42000 --no-browser

doc/README.md

@@ -0,0 +1,7 @@
+# plotnine-docs-demo
+
+This repo migrates the plotnine docs from sphinx to quarto (using quartodoc).
+
+* [site preview](https://main--plotnine-docs-demo.netlify.app)
+* [original site on readthedocs](https://plotnine.readthedocs.io/en/stable/)
+* [has2k1/plotnine repo](https://github.com/has2k1/plotnine)

doc/_config.py

@@ -0,0 +1,73 @@
+import hashlib
+import re
+import shutil
+from importlib.metadata import version as get_version
+from importlib.resources import files as _files
+from pathlib import Path
+
+DOC_DIR = Path(__file__).parent
+
+# The environment file holds the version
+ENV_TPL = """\
+VERSION={version}
+"""
+
+
+def generate_environment_file():
+    """
+    Generate _enviroment file in the quartodoc project directory
+    """
+    version = get_version("plotnine")
+    filepath = DOC_DIR / "_environment"
+
+    # The scm-version scheme adds .date suffix to the version
+    # if the repo is dirty. For better look while developing,
+    # we remove it.
+    dirty_pattern = re.compile(r"\.d\d{8}$")
+    if dirty_pattern.search(version):
+        version = dirty_pattern.sub("", version)
+
+    # FIXME: We return because modifying the _environment file
+    # breaks "quarto render"
+    if filepath.exists():
+        return
+
+    contents = ENV_TPL.format(version=version)
+    filepath.write_text(contents)
+
+
+def copy_examples_and_tutorials():
+    """
+    Copy the examples & tutorials in plotnine_examples
+    """
+
+    # NOTE: To avoid confusing the watcher used by "quarto preview",
+    # we copy only if the original files are different.
+    def same_contents(f1, f2):
+        h1 = hashlib.md5(f1.read_bytes()).hexdigest()
+        h2 = hashlib.md5(f2.read_bytes()).hexdigest()
+        return h1 == h2
+
+    def copy(src_dir, dest_dir):
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        src_files = src_dir.glob("*.ipynb")
+        cur_dest_files = dest_dir.glob("*.ipynb")
+        new_dest_files = []
+        for src in src_files:
+            dest = dest_dir / src.name
+            new_dest_files.append(dest)
+            if dest.exists() and same_contents(src, dest):
+                continue
+            shutil.copyfile(src, dest)
+
+        # Remove any deleted files
+        for dest in set(cur_dest_files).difference(new_dest_files):
+            dest.unlink()
+
+    copy(_files("plotnine_examples.examples"), DOC_DIR / "examples")
+    copy(_files("plotnine_examples.tutorials"), DOC_DIR / "tutorials")
+
+
+if __name__ == "__main__":
+    generate_environment_file()
+    copy_examples_and_tutorials()

doc/_extensions/machow/interlinks/.gitignore

@@ -0,0 +1,3 @@
+*.html
+*.pdf
+*_files/

doc/_extensions/machow/interlinks/_extension.yml

@@ -0,0 +1,7 @@
+title: Interlinks
+author: Michael Chow
+version: 1.0.0
+quarto-required: ">=1.2.0"
+contributes:
+  filters:
+    - interlinks.lua