9082 educate users on mat mul precision

docs/.gitattributes

@@ -0,0 +1 @@
+*.ipynb diff=none merge=binary

docs/README.md

@@ -28,4 +28,49 @@ git push origin gh-pages
 To add a new doc please create a `.md` file under this directory. To make this doc show up in our [doc pages](https://pytorch.org/xla/master/index.html), please add a `.rst` file under `source/`.
 
 ## Adding images in the doc
-Please add your imges to both `_static/img/` and `source/_static/img/` for images to properlly show up in the markdown files as well as our [doc pages](https://pytorch.org/xla/master/index.html).
+Please add your imges to both `_static/img/` and `source/_static/img/` for images to properly show up in the markdown files as well as our [doc pages](https://pytorch.org/xla/master/index.html).
+
+## Runnable tutorials
+
+Stylistically, review the [pytorch tutorial contributing guide](https://github.com/pytorch/tutorials/blob/main/CONTRIBUTING.md).
+
+Save your tutorial as `*_tutorial.py`.
+
+We do not yet have an automated build system for runnable tutorials that matches 
+PyTorch. For now, include manual instructions and check-in the output ipynb and MD files. 
+
+TODO: Automate build of runnable tutorials. https://github.com/pytorch/xla/issues/9136
+
+Note that the existing .gitattributes in this directory will prevent diffs and merges
+on the ipynb's json representation, which is difficult to diff. 
+
+Add your runnable tutorial to the list below with build instructions, 
+necessary environments, and steps to manually verify correctness.
+
+### source/tutorials/precision_tutorial.py
+
+Run on a TPU machine. 
+
+One time installs not in requirements.txt:
+
+```sh
+conda install -c conda-forge pandoc
+```
+
+Run every time: 
+
+```sh
+py2nb source/tutorials/precision_tutorial.py
+jupyter nbconvert --to notebook --execute --inplace source/tutorials/precision_tutorial.ipynb 
+# Ignore SIGTERM
+# Manually verify that the final line of precision_tutorial.ipynb matches the snippet below.
+./docs_build.sh
+# Download build/ to your local machine and visually inspect the precision_tutorial.html in a browser. 
+# Look for issues like headers that didn't render and mathjax that didn't render. 
+```
+
+The final code output in the ipynb and html should look like this: 
+```
+    Z_ref: FORMAT:0b SIGN:0 EXPONENT:01111111 MANTISSA:01110000101000111101100 VALUE=1.440000057220459
+    Z:     FORMAT:0b SIGN:0 EXPONENT:01111111 MANTISSA:01110000101000111101101 VALUE=1.4400001764297485
+```

docs/requirements.txt

@@ -4,3 +4,6 @@ docutils==0.16
 Jinja2==3.1.3
 m2r
 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
+py2nb==1.0.0
+nbsphinx==0.9.3
+lxml[html_clean] # Workaround for an issue in nbsphinx