[make_docs.sh] Add support for executing tutorials

scripts/make_docs.sh

@@ -22,7 +22,7 @@ usage() {
 
 BUILD_STATIC=false
 ONLY_DOCUSAURUS=false
-BUILD_TUTORIALS=false
+EXECUTE_TUTORIALS=false
 INSERT_API_REFS=false
 
 while getopts 'hbotrk:' flag; do
@@ -37,7 +37,7 @@ while getopts 'hbotrk:' flag; do
       ONLY_DOCUSAURUS=true
       ;;
     t)
-      BUILD_TUTORIALS=true
+      EXECUTE_TUTORIALS=true
       ;;
     r)
       INSERT_API_REFS=true
@@ -48,6 +48,13 @@ while getopts 'hbotrk:' flag; do
   esac
 done
 
+if [[ $EXECUTE_TUTORIALS == true ]]; then
+  echo "-----------------------------------"
+  echo "Executing tutorials"
+  echo "-----------------------------------"
+  python3 scripts/run_tutorials.py -w "${cwd}"
+fi
+
 if [[ $ONLY_DOCUSAURUS == false ]]; then
   echo "-----------------------------------"
   echo "Generating tutorials"

website/README.md

@@ -1,20 +1,41 @@
 The Ax website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-## Building
+## Building (All-in-one)
 
-### Notebooks
-We convert tutorial notebooks to MDX for embedding as docs. This needs to be done before serving the website and can be done by running this script from the project root:
+For convenience we provide a single shell script to convert the tutorials and build the website in one command:
+```bash
+./scripts/make_docs.sh
+```
 
+To also execute the tutorials, run
 ```bash
-python3 scripts/convert_ipynb_to_mdx.py --clean
+./scripts/make_docs.sh -t
+```
+
+To generate a static build of the website in the `website/build` directory, run
+```bash
+./scripts/make_docs.sh -b
 ```
 
-If the script fails ensure you have the necessary dependencies (ideally to your virtual env):
+## Building (manually)
 
+### Notebooks
+Ensure necessary dependencies are installed (ideally to your virtual env):
 ```bash
 pip install -e ".[tutorial]"
 ```
 
+Tutorials can be executed locally using the following script. This is optional for locally building the website and is slow.
+```bash
+python3 scripts/run_tutorials.py -w .
+```
+
+We convert tutorial notebooks to MDX for embedding as docs. This needs to be done before serving the website and can be done by running this script from the project root:
+
+```bash
+python3 scripts/convert_ipynb_to_mdx.py --clean
+```
+
 ### Docusaurus
 You need [Node](https://nodejs.org/en/) >= 18.x and
 [Yarn](https://yarnpkg.com/en/) in order to build the Ax website.
@@ -32,18 +53,21 @@ Anytime you change the contents of the page, the page should auto-update.
 
 Note that you may need to switch to the "Next" version of the website documentation to see your latest changes.
 
-### All-in-one
-
-For convenience we provide a single shell script to convert the tutorials and build the website in one command:
-```bash
-./scripts/make_docs.sh
+### Sphinx
+Sphinx is used to generate an API reference from the source file docstrings. In production we use ReadTheDocs to build and host these docs, but they can also be built locally for testing.
+```sh
+cd sphinx/
+make html
 ```
 
-To generate a static build of the website in the `website/build` directory, run
-```bash
-./scripts/make_docs.sh -b
+The build output is in `sphinx/build/` but Sphinx does not provide a server. There are many ways to view the output, here's an example using python:
+
+```sh
+cd sphinx/build/
+python3 -m http.server 8000
 ```
 
+
 ## Publishing
 
 The site is hosted on GitHub pages, via the `gh-pages` branch of the Ax