From aefc94e1654d69a0ec167af73d3748e829d7b863 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A5kon=20Wiik=20=C3=85nes?= <hwaanes@gmail.com>
Date: Wed, 1 Nov 2023 19:50:13 +0100
Subject: [PATCH] Install pandoc version supported by nbconvert on RTD
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>
---
 doc/dev/running_writing_tests.rst | 19 ++++++++++++++-----
 doc/environment.yml               |  5 +++++
 readthedocs.yaml                  |  6 ++++--
 3 files changed, 23 insertions(+), 7 deletions(-)
 create mode 100644 doc/environment.yml

diff --git a/doc/dev/running_writing_tests.rst b/doc/dev/running_writing_tests.rst
index 174051fe..092f1ee2 100644
--- a/doc/dev/running_writing_tests.rst
+++ b/doc/dev/running_writing_tests.rst
@@ -9,7 +9,7 @@ Install necessary dependencies to run the tests::
 
     pip install --editable .[tests]
 
-Some useful :doc:`fixtures <pytest:explanation/fixtures>`, like a dummy scan and
+Some useful :doc:`fixtures <pytest:explanation/fixtures>`, like a dummy EBSD scan and a
 corresponding background pattern, are available in the ``conftest.py`` file.
 
 .. note::
@@ -33,13 +33,22 @@ For an even nicer presentation, you can use ``coverage.py`` directly::
 Then, you can open the created ``htmlcov/index.html`` in the browser and inspect the
 coverage in more detail.
 
-To run only a specific test function or class, .e.g the ``TestEBSD`` class::
+We can run tests in parallel on four CPUs using pytest-xdist::
+
+    pytest -n 4
+
+To run only a specific test function or class, e.g. the ``TestEBSD`` class::
 
     pytest -k TestEBSD
 
-This is useful when you only want to run a specific test and not the full test suite,
-e.g. when you're creating or updating a test.
-But remember to run the full test suite before pushing!
+This is useful when we only want to run a specific test and not the full test suite,
+e.g. when we're creating or updating a test.
+We have to remember to run the full test suite before pushing, though!
+
+We can automatically rerun so-called flaky tests (tests yielding both passing and
+failing results without code changes) using the pytest plugin pytest-rerunfailures::
+
+    pytest --reruns 2
 
 Docstring examples are tested :doc:`with pytest <pytest:how-to/doctest>` as well.
 If you're in the top directory you can run::
diff --git a/doc/environment.yml b/doc/environment.yml
new file mode 100644
index 00000000..239ce05a
--- /dev/null
+++ b/doc/environment.yml
@@ -0,0 +1,5 @@
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - pandoc>=2.14.2, <4.0.0
\ No newline at end of file
diff --git a/readthedocs.yaml b/readthedocs.yaml
index 0bd4c29b..40a03e5b 100644
--- a/readthedocs.yaml
+++ b/readthedocs.yaml
@@ -13,14 +13,13 @@ sphinx:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "mambaforge-22.9"
     nodejs: "19"
   # Some of these packages are needed by PyVista/Trame to render 3D
   # plots from RTD's server.
   apt_packages:
     - imagemagick
     - libgl1-mesa-dev
-    - pandoc
     - xvfb
 
 # Build doc in all formats (HTML, PDF and ePub)
@@ -28,6 +27,9 @@ formats:
   - htmlzip
   - pdf
 
+conda:
+  environment: doc/environment.yml
+
 # Python environment for building the docs
 python:
   install: