start RTD integration (#293)

* start RTD integration

* sphinx_markdown_tables

* typo

* allow crappy rst because rst is crappy

* reconmark

* declare recommonmark as an extension

.readthedocs.yaml

@@ -0,0 +1,40 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "mambaforge-4.10"
+
+  jobs:
+    post_checkout:
+      # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
+      # You can add any other files or directories that you'd like here as well,
+      # like your docs requirements file, or other files that will change your docs build.
+      #
+      # If there are no changes (git diff exits with 0) we force the command to return with 183.
+      # This is a special exit code on Read the Docs that will cancel the build immediately.
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- doc/ .readthedocs.yaml;
+        then
+          exit 183;
+        fi
+      - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
+
+  apt_packages:
+    - graphviz
+
+formats:
+  - pdf
+  - epub
+
+conda:
+  environment: doc/environment.yml
+
+sphinx:
+  builder: html
+  configuration: doc/source/conf.py

doc/environment.yml

@@ -0,0 +1,17 @@
+name: entwine
+channels:
+  - conda-forge
+dependencies:
+  - compilers
+  - cmake
+  - ninja
+  - pip
+  - pip:
+    - breathe
+    - pybtex
+    - sphinx-rtd-theme
+    - sphinxcontrib-bibtex
+    - sphinxcontrib-spelling
+    - sphinx_markdown_tables
+    - recommonmark
+    - sphinxcontrib-spelling!=7.4.0

doc/source/conf.py

@@ -33,6 +33,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx_markdown_tables',
+    'recommonmark',
     'sphinxcontrib.spelling'
 ]