DOC: PR Template update (Azure#116)

* PR Template update

* updating doc contributor guide

* updating guidance

* fixing build

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,17 +14,13 @@
 <!--- If you are considering making a contribution please open an issue first. -->
 <!--- This can help in identifying if the contribution fits into the plans for PyRIT. -->
 <!--- Maintainers may be aware of obstacles that aren't obvious, or clarify requirements, and thereby save you time. -->
-<!--- Note that contributions require tests and documentation (if applicable). -->
-<!--- See the section below and check the boxes that apply. -->
 
-## Tests
-<!--- Select all that apply by putting an x between the brackets: [x] -->
-- [ ] no new tests required
-- [ ] new tests added
-- [ ] existing tests adjusted
 
-## Documentation
-<!--- Select all that apply by putting an x between the brackets: [x] -->
-- [ ] no documentation changes needed
-- [ ] documentation added or edited
-- [ ] example notebook added or updated
+## Tests and Documentation
+
+<!--- Contributions require tests and documentation (if applicable). -->
+<!--- Include a description of tests and documentation updated (if applicable) -->
+
+<!--- JupyText helps us see regressions in APIs or in our documentation by executing all code samples -->
+<!--- Include how you/if ran JupyText here -->
+<!--- This is described at: https://github.com/Azure/PyRIT/tree/main/doc  -->

doc/README.md

@@ -12,10 +12,16 @@ Most of our documentation is located within the `doc` directory:
 
 # Documentation Contributor Guide
 
-- All documentation should be a `.md` file or a `.py` file in the percent format file (this will generate to `.ipynb` for consumption)
-  - Do not update `.ipynb` files directly. These are meant for consumption only and will be overwritten
-- The code should be able to execute one time in a reasonable timeframe, our goal is to run this in build pipelines
-  - Short term, before we have it in our build pipelines, please run it manually with any big changes and check there are no errors
-  - Currently, run: ` jupytext --execute --to notebook  ./doc/demo/*.py` and `jupytext --execute --to notebook  ./doc/code/*.py`
-  - Soon this will be: `pre-commit run jupytext --all-files`
-  - Please do not re-commit updated generated `.ipynb` files with slight changes if nothing has changed in the source
+All documentation should be a `.md` file or a `.py` file in the percent format file. We then use jupytext to execute this code and convert to `.ipynb` for consumption.
+
+We have several reasons for this. 1) `.py` and `.md` files are much easier to review. 2) documentation code was tough to keep up to date without running it (which we can do automatically with jupytext). 3) It gives us some level of integration testing; if models change from underneath us, we have some way of detecting the changes.
+
+Here are contributor guidelines:
+
+- Do not update `.ipynb` files directly. These are meant for consumption only and will be overwritten.
+- The code should be able to execute in a reasonable timeframe. Before we build out test infrastructure, we often run this manually and long running files are not ideal. Not all code scenarios need to be documented like this in code that runs. Consider adding unit tests and mocking.
+- This code often connects to various endpoints so it may not be easy to run (not all contributors will have everything deployed). However, it is an expectation that maintainers have all documented infrastructure available and configured.
+  - Contributors: if your notebook updates a `.py` file or how it works specifically, rerun it as ` jupytext --execute --to notebook  ./doc/affected_file.py`
+  - Maintainers (bonus if contributors do this also): If there are big changes, re-generate all notebooks by using [run_jupytext.ps1](./run_jupytext.ps1) or [run_jupytext.sh](./run_jupytext.sh)
+- Some contributors use jupytext to generate `.py` files from `.ipynb` files. This is also acceptable.
+- Please do not re-commit updated generated `.ipynb` files with slight changes if nothing has changed in the source

doc/run_jupytext.ps1

@@ -0,0 +1,7 @@
+$currDir = Split-Path -Parent -Path $MyInvocation.MyCommand.Definition
+$files = Get-ChildItem -Path $currDir -Recurse -Include *.py -File
+
+foreach ($file in $files) {
+    write-host "Processing $file"
+    jupytext --execute --to notebook $file.FullName
+}

doc/run_jupytext.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+curr_dir="$(dirname "$(realpath "$0")")"
+find "$curr_dir" -type f -name "*.py" -print0 | while IFS= read -r -d '' file
+do
+    echo "Processing $file"
+    jupytext --execute --to notebook "$file"
+done