From 0ce3182f02e2b556131570b58587f4876abaddb5 Mon Sep 17 00:00:00 2001
From: rlundeen2 <137218279+rlundeen2@users.noreply.github.com>
Date: Tue, 26 Mar 2024 11:20:03 -0700
Subject: [PATCH] DOC: PR Template update (#116)

* PR Template update

* updating doc contributor guide

* updating guidance

* fixing build
---
 .github/PULL_REQUEST_TEMPLATE.md | 20 ++++++++------------
 doc/README.md                    | 20 +++++++++++++-------
 doc/run_jupytext.ps1             |  7 +++++++
 doc/run_jupytext.sh              |  8 ++++++++
 4 files changed, 36 insertions(+), 19 deletions(-)
 create mode 100644 doc/run_jupytext.ps1
 create mode 100644 doc/run_jupytext.sh

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 561da67dd..8af748187 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.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  -->
diff --git a/doc/README.md b/doc/README.md
index 307903c73..5b855a9bf 100644
--- a/doc/README.md
+++ b/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
diff --git a/doc/run_jupytext.ps1 b/doc/run_jupytext.ps1
new file mode 100644
index 000000000..6ad870e20
--- /dev/null
+++ b/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
+}
diff --git a/doc/run_jupytext.sh b/doc/run_jupytext.sh
new file mode 100644
index 000000000..000dcdf05
--- /dev/null
+++ b/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