Add doc examples (#59)

* fix: hide stdout output

* docs: document how we gen gallery in `conf.py`

* fix: fix random shuffle in rose plotter

* docs: update rose plotter doc

* refactor: make line plotter more robust

* feat: add more examples

* fix: let linguist work correctly

* chore: add a contributing guide

* chore: add pull request template

* test: add a test for line plotter

* build: add a `noplot` target to makefile

* docs: add visualisations design considerations

* fix: fix a typo

* docs: replace note with warning

* docs: update `show` doc

* docs: remove the warning from word plotter example

* ci: specify the backend for matplotlib

in case that the test fails in Windows

* ci: reformat the workflows files

* chore: try bumping word plotter support again

* docs: adjust the warnings

* fix: resolve some issues

* docs: fix typos

* docs: add docs for no-plot build

* docs: update bubble plotter doc

---------

Co-authored-by: KD-7 <[email protected]>

Author: yuxqiu

.gitattributes

@@ -0,0 +1 @@
+truelearn/tests/baseline_files/* linguist-vendored

.github/CONTRIBUTING.md

@@ -0,0 +1,2 @@
+Welcome! We’re happy to have you here. Thank you in advance for your contribution to TrueLearn.
+Please see: [Contributing Guide](https://truelearn.readthedocs.io/en/latest/dev/index.html) for more information!

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+Thanks for contributing a pull request to TrueLearn!
+
+Please ensure you have taken a look at the contribution guidelines:
+https://truelearn.readthedocs.io/en/latest/dev/index.html
+-->
+
+### Reference Issues/PRs
+
+<!--
+Example: Fixes #1234. See also #3456.
+
+Please use keywords (e.g., Fixes) to create link to the issues or pull requests
+you resolved, so that they will automatically be closed when your pull request
+is merged. See https://github.com/blog/1506-closing-issues-via-pull-requests
+-->
+
+
+### What are the changes/fixes in this PR?
+
+<!--
+Here is an example of what you can write in this section:
+
+1. What did you do?
+2. Why? Explain the motivation.
+3. The design choices you make and the reasons behind them
+4. [Optional] Any new benchmarks and tests added that are worth mentioning?
+-->

.github/workflows/black.yml

@@ -3,9 +3,9 @@ on:
   pull_request:
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/black.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/black.yml"
   workflow_dispatch:
   workflow_call:
 

.github/workflows/coverage.yml

@@ -5,15 +5,15 @@ on:
       - main
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/coverage.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/coverage.yml"
   pull_request:
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/coverage.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/coverage.yml"
   workflow_dispatch:
 
 # Only cancel concurrent runs of the same workflow

.github/workflows/python_publish.yml

@@ -9,11 +9,10 @@ on:
 
   workflow_dispatch:
     inputs:
-        pypi_release_type:
-            description: 'Release to TestPyPI or PyPI (testpypi or pypi)'
-            required: true
-            default: 'testpypi'
-
+      pypi_release_type:
+        description: "Release to TestPyPI or PyPI (testpypi or pypi)"
+        required: true
+        default: "testpypi"
 
 permissions:
   contents: read
@@ -78,4 +77,3 @@ jobs:
         with:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}
-

.github/workflows/static_analysis.yml

@@ -5,15 +5,15 @@ on:
       - main
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/static_analysis.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/static_analysis.yml"
   pull_request:
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/static_analysis.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/static_analysis.yml"
   workflow_dispatch:
   workflow_call:
 

.github/workflows/unit_tests.yml

@@ -5,28 +5,27 @@ on:
       - main
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/unit_tests.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/unit_tests.yml"
   pull_request:
     # filter on files that should trigger this workflow
     paths:
-      - 'pyproject.toml'
-      - '**.py'
-      - '.github/workflows/unit_tests.yml'
+      - "pyproject.toml"
+      - "**.py"
+      - ".github/workflows/unit_tests.yml"
   workflow_dispatch:
   workflow_call:
     inputs:
       environment:
         required: true
-        default: 'testing'
+        default: "testing"
         type: string
-        description: 'Environment to run tests in (testing)'
+        description: "Environment to run tests in (testing)"
     secrets:
       WIKIFIER_API_KEY:
         required: true
-        description: 'Wikifier API Key'
-
+        description: "Wikifier API Key"
 
 # Only cancel concurrent runs of the same workflow
 concurrency:
@@ -44,6 +43,9 @@ jobs:
 
     env:
       WIKIFIER_API_KEY: ${{ secrets.WIKIFIER_API_KEY }}
+      # necessary for matplotlib to work properly in Windows
+      # it fails occasionally if we don't set this
+      MPLBACKEND: "Agg"
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v3

docs/Makefile

@@ -12,6 +12,13 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Generate doc without running the examples
+# Can speed up doc build time when you don't need the examples
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	@echo
+	@echo "No-plot build finished. The HTML pages are in $(BUILDDIR)/html."
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/conf.py

@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import inspect
+import warnings
 import os
 import shutil
 import sys
@@ -46,6 +47,16 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.doctest",
     "sphinx_copybutton",
+    # for some mysterious reason, if we put sphinx_gallery
+    # below autosummary (which means if it is loaded after autosummary),
+    # trueskill in truelearn.learning will not be properly
+    # imported (``dir(trueskill)`` does not include trueskill
+    # methods and classes and ``trueskill.__all__`` is an empty list)
+    #
+    # Note: An alternative solution is to add a higher priority of
+    # ``generate_gallery_rst`` method in ``sphinx_gallery.gen_gallery``
+    # which controls the gallery generation. It is registered via
+    # app.connect('builder-inited', generate_gallery_rst).
     "sphinx_gallery.gen_gallery",
     "sphinx.ext.autosummary",
 ]
@@ -108,6 +119,7 @@ def find_source():
 
 # -- Gallery configuration ---------------------------------------------------
 from plotly.io._sg_scraper import plotly_sg_scraper
+from sphinx_gallery.sorting import ExampleTitleSortKey
 
 image_scrapers = (
     "matplotlib",
@@ -122,12 +134,27 @@ def find_source():
     "examples_dirs": "../examples",  # path to your example scripts
     "gallery_dirs": "examples",  # path to where to save gallery generated output,
     "download_all_examples": False,  # disable download file buttons
+    "within_subsection_order": ExampleTitleSortKey,  # sort examples by title
     "remove_config_comments": True,
     "show_memory": False,
     "show_signature": False,
+    "plot_gallery": "True",
     "image_scrapers": image_scrapers,
 }
 
+# filter WordPlotter warnings because we already have
+# an admonition in the WordPlotter example
+warnings.filterwarnings(
+    "ignore",
+    category=FutureWarning,
+    message=(
+        "WordPlotter may be removed in a future release "
+        "because wordcloud library does not have "
+        r"cross-platform support for Python 3.11\+, "
+        r"and it is not actively maintained\."
+    ),
+)
+
 # -- Options for napoleon extension ------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
 napoleon_include_special_with_doc = False