add sphinx gallery setup and first example to submit job

Signed-off-by: vsoch <[email protected]>

.devcontainer/Dockerfile

@@ -13,6 +13,9 @@ ENV PYTHONPATH=/usr/lib/flux/python3.8
 # For easier Python development.
 RUN python3 -m pip install IPython && \
     python3 -m pip install -r /requirements.txt && \
-    python3 -m pip install -r /dev-requirements.txt
+    python3 -m pip install -r /dev-requirements.txt && \
+    # For developer convenience
+    ln -s /usr/bin/python3 /usr/bin/python
 
 ENV PATH=/env/bin:${PATH}
+WORKDIR /workspace/flux-docs

.github/scripts/check_diff.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+
+# This script checks that two directories are recursively equal
+# however we only care about name (existence) and timestamp.
+# Usage:
+#  python .github/scripts/check_diff.py /tmp/auto_examples ./auto_examples
+
+import argparse
+import os
+import fnmatch
+
+
+def recursive_find(base, pattern="*.*"):
+    """
+    Get a list of all files in a root.
+
+    We need full and relative paths, so just assemble that.
+    """
+    files = {}
+    for root, _, filenames in os.walk(base):
+        for filename in fnmatch.filter(filenames, pattern):
+            fullpath = os.path.join(root, filename)
+            relpath = os.path.relpath(fullpath, base)
+            files[relpath] = fullpath
+    return files
+
+
+def get_parser():
+    """
+    Get a parser to retrieve two directories.
+    """
+    parser = argparse.ArgumentParser(
+        description="🤒️ Not terribly accurate directory comparison tool."
+    )
+    parser.add_argument("dir_a", help="the first directory")
+    parser.add_argument("dir_b", help="the second directory")
+    return parser
+
+
+def main():
+    parser = get_parser()
+    args = parser.parse_args()
+
+    # Both directories must exist
+    for dirname in args.dir_a, args.dir_b:
+        if not os.path.exists(dirname):
+            sys.exit(f"😢️ {dirname} does not exist.")
+
+    print(f"🐨️ Checking for differences between {args.dir_a} and {args.dir_b}")
+
+    # Lookup of relative -> fullpath
+    files_a = recursive_find(args.dir_a)
+    files_b = recursive_find(args.dir_b)
+
+    # The relative paths should match
+    A = set(files_a)
+    B = set(files_b)
+    if A.difference(B):
+        sys.exit(
+            f"😢️ Auto examples were not updated! Difference between sets:\n{A.difference(B)}"
+        )
+
+    # Now for each file check the size
+    for key, file_a in files_a.items():
+        file_b = files_b[key]
+        stat_a = os.stat(file_a)
+        stat_b = os.stat(file_b)
+        if stat_a.st_size != stat_b.st_size:
+            sys.exit(
+                f"😢️ Auto examples were not updated! Different size of {key}:\n{stat_a.st_size} vs. {stat_b.st_size}"
+            )
+
+    print(f"😃️ Yay! No differences between {args.dir_a} and {args.dir_b}")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/main.yml

@@ -12,6 +12,24 @@ jobs:
     - run: git fetch origin master
     - uses: flux-framework/pr-validator@master
 
+  check-examples:
+    name: ensure latest examples built
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+        fetch-depth: 0
+
+    - name: Build Docs and Check Files
+      uses: devcontainers/[email protected]
+      with:
+        runCmd: |
+          cp -R ./auto_examples /tmp/auto_examples
+          flux start make html
+          echo "Testing that you built the auto-examples, if this fails run flux start make html locally."
+          python .github/scripts/check_diff.py /tmp/auto_examples ./auto_examples
+          
   spelling:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -2,7 +2,17 @@
 
 Edits should be made to the `.rst` files.
 The documentation can be built with `make html` or `make man`.
-The generated files will be found in the `_build` directory.
+The generated files will be found in the `_build` directory. Note that if you
+want to build the docs, it is recommended to use the development environment to have
+the Flux Python bindings available, e.g.,:
+
+```python
+import flux
+# no error
+```
+
+If you build the docs in an environment without the bindings, the sphinx gallery examples
+will not properly generate. This is OK if you don't edit them.
 
 ## VSCode Development Container
 
@@ -11,6 +21,26 @@ to provide an environment for you to easily work on the documentation, and ensur
 is installed to generate some of our Sphinx Gallery (TBA) tutorials. This works by way
 of the assets in [.devcontainer](https://code.visualstudio.com/docs/remote/containers#_create-a-devcontainerjson-file).
 
+## Manual Development Container
+
+If you want to generate the container manually, this is also an option! First build it:
+
+```bash
+$ docker build -f ./.devcontainer/Dockerfile -t flux-docs .
+```
+This will build the base environment. You can then bind your container to the present working directory to
+build, either interactively:
+
+```bash
+$ docker run -it --rm -v $PWD/:/workspace/flux-docs flux-docs flux start make html
+```
+
+You can also go in interactively - just be careful and don't commit from within the container.
+
+```bash
+$ docker run -it --rm -v $PWD/:/workspace/flux-docs flux-docs bash
+```
+
 ### Setup
 
 You can follow the [tutorial](https://code.visualstudio.com/docs/remote/containers-tutorial) where you'll basically
@@ -26,11 +56,19 @@ While this uses the focal base, you are free to change the base image and rebuil
 When your container is built, when you open `Terminal -> New Terminal` and you'll be in the container! 
 You should be able to build docs:
 
+```bash
+$ flux start make html
+```
+
+If you don't have Flux Python bindings or don't want to generate them, just fall back
+to:
+
 ```bash
 $ make html
 ```
 
-And then you can do as you would do on your host to start a local webserver:
+The build will detect that the Flux Python bindings are not available and build everything
+except for the examples gallery. And then you can do as you would do on your host to start a local webserver:
 
 ```console
 ..
@@ -46,11 +84,12 @@ We will provide further instructions here for building sphinx examples as they a
 
 **Important** it's recommended that you commit (or otherwise write to the .git folder) from the outside
 of the container. This will allow you to sign commits with your (not mounted to the container) key,
-and will ensure the permissions of the commit are not done by a root user.
-If you accidentally do this and need to fix, you can run this from your terminal outside of VSCode:
+and will ensure the permissions of the commit are not done by a root user. If you update the sphinx
+examples, the permissions can also get wonky. In either case, you can run this from your terminal outside of VSCode:
 
 ```bash
-$ sudo chown -R $USER .git/
+$ sudo chown -R $USER .
+$ sudo chown -R $USER .git/ .
 # and then commit
 ```