Fix JupyterBook formatting and add the executable notebooks to CI tes…

…ts. (#647)

* Fix JupyterBook formatting and add the executable notebooks to CI tests.

* Give doctest the same 'pr' trigger as buildtest.

* Use Ubuntu 18.04, not 16.04. That's ancient.

* Build Awkward Array so that the notebooks can succeed.

* Swap trigger vs PR to build only PR version.

* Install all the requirements needed for running documentation.

.ci/azure-doctest-awkward.yml

@@ -1,28 +1,19 @@
 trigger:
   batch: true
+  branches:
+    exclude:
+      - "*"
+
+pr:
   branches:
     include:
       - "*"
-  paths:
-    exclude:
-      - README.md
-      - VERSION_INFO
-      - .ci/azure-deploy-awkward.yml
-      - .ci/linux-build.sh
-      - .readthedocs.yml
-      - docs-src/*
-      - docs-img/*
-      - docs-jupyter/*
-      - docs-doxygen/*
-      - docs-sphinx/*
-      - docs/*
-      - studies/*
 
 jobs:
-  - job: Linux
+  - job: Sphinx
 
     pool:
-      vmImage: "ubuntu-16.04"
+      vmImage: "ubuntu-18.04"
 
     strategy:
       matrix:
@@ -53,3 +44,50 @@ jobs:
       - script: |
           sphinx-build docs-sphinx/ docs-sphinx/_build/
         displayName: "Generate documentation"
+
+  - job: JupyterBook
+
+    pool:
+      vmImage: "ubuntu-18.04"
+
+    strategy:
+      matrix:
+        "py38-np*":
+          python.version: "3.8"
+          python.architecture: "x64"
+
+    steps:
+      - checkout: self
+        submodules: recursive
+
+      - task: UsePythonVersion@0
+        inputs:
+          versionSpec: '$(python.version)'
+          architecture: '$(python.architecture)'
+        displayName: 'Python $(python.version)'
+
+      - script: |
+          python -m pip install --upgrade pip
+        displayName: "Install Pip"
+
+      - script: |
+          python -m pip install -r docs-src/requirements.txt
+        displayName: "Install dependencies"
+
+      - script: |
+          python -m pip install -v .
+        displayName: "Build Awkward Array"
+
+      - script: |
+          jupyter-book build docs-src
+        displayName: "Run notebooks"
+
+      - script: |
+          for x in `ls docs-src/_build/html/reports/*.log 2> /dev/null`; do
+              echo '===================================================================';
+              echo $x;
+              echo '===================================================================';
+              cat $x;
+          done
+          [ ! -d "docs-src/_build/html/reports" ]
+        displayName: "Check reports"

docs-src/_config.yml

@@ -3,11 +3,26 @@ author: "Jim Pivarski"
 copyright: "2020 Jim Pivarski"
 logo: img/logo-300px.png
 
-html:
-  favicon: img/favicon.ico
+repository:
+  url: https://github.com/scikit-hep/awkward-1.0
 
 launch_buttons:
   binderhub_url: ""
 
-repository:
-  url: https://github.com/scikit-hep/awkward-1.0
+execute:
+  allow_errors: false
+
+sphinx:
+  config:
+    html_favicon: img/favicon.ico
+    html_theme_options:
+      home_page_in_toc: true
+      repository_url: https://github.com/scikit-hep/awkward-1.0
+      repository_branch: main
+      path_to_docs: docs-src
+      use_edit_page_button: true
+      use_issues_button: true
+      search_bar_text: Search...
+      google_analytics_id: ""
+      extra_navbar: ""
+      show_navbar_depth: 2

docs-src/_toc.yml

@@ -6,7 +6,6 @@
 
 - file: how-to-convert
   title: "Converting arrays"
-  expand_sections: true
   sections:
     - file: how-to-convert-numpy
       title: "NumPy"
@@ -25,7 +24,6 @@
 
 - file: how-to-create
   title: "Creating new arrays"
-  expand_sections: true
   sections:
     - file: how-to-create-arraybuilder
       title: "ArrayBuilder (easy & general)"
@@ -46,7 +44,6 @@
 
 - file: how-to-examine
   title: "Examining arrays"
-  expand_sections: true
   sections:
     - file: how-to-examine-type
       title: "Data type"
@@ -61,7 +58,6 @@
 
 - file: how-to-math
   title: "Numerical math"
-  expand_sections: true
   sections:
     - file: how-to-math-numpy
       title: "NumPy functions"
@@ -78,7 +74,6 @@
 
 - file: how-to-filter
   title: "Filtering data"
-  expand_sections: true
   sections:
     - file: how-to-filter-num
       title: "By number of items"
@@ -91,7 +86,6 @@
 
 - file: how-to-restructure
   title: "Restructuring data"
-  expand_sections: true
   sections:
     - file: how-to-restructure-zip-project
       title: "Zip/unzip and project"
@@ -110,7 +104,6 @@
 
 - file: how-to-combinatorics
   title: "Combinatorics"
-  expand_sections: true
   sections:
     - file: how-to-combinatorics-cartesian-combinations
       title: 'Cartesian product and "n choose k"'
@@ -119,7 +112,6 @@
 
 - file: how-to-use-in-numba
   title: "Using arrays in Numba"
-  expand_sections: true
   sections:
     - file: how-to-use-in-numba-features
       title: "Supported features"
@@ -128,7 +120,6 @@
 
 - file: how-to-specialize
   title: "Specialized behavior"
-  expand_sections: true
   sections:
     - file: how-to-specialize-subclass
       title: "Subclassing Array/Record"

docs-src/requirements.txt

@@ -0,0 +1,12 @@
+setuptools
+numpy>=1.13.1
+numba>=0.50.0
+pandas>=0.24.0
+numexpr
+autograd
+pyarrow>=2.0.0
+h5py
+matplotlib
+uproot
+uproot3
+jupyter-book