From 0c3935208eee2696de2a99ca8ea11a4d5dac34a3 Mon Sep 17 00:00:00 2001
From: BHT <toby@anl.gov>
Date: Thu, 16 Jan 2025 12:31:00 -0600
Subject: [PATCH] add build guide; build tutorial index after MDtutorials build

---
 .github/workflows/builddocsite.yml | 20 +++----
 MDtutorials/TutorialGuide.txt      | 85 ++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+), 10 deletions(-)
 create mode 100644 MDtutorials/TutorialGuide.txt

diff --git a/.github/workflows/builddocsite.yml b/.github/workflows/builddocsite.yml
index fb6c931..137c301 100644
--- a/.github/workflows/builddocsite.yml
+++ b/.github/workflows/builddocsite.yml
@@ -37,14 +37,6 @@ jobs:
         run: |
           curl -L https://github.com/AdvancedPhotonSource/GSAS-II/raw/master/GSASII/tutorialIndex.py -o scripts/tutorialIndex.py
 
-      - name: build tutorials index 
-        run: |
-          cd scripts
-          python makeGitTutorial.py ..
-      
-      - name: Push changes
-        uses: ad-m/github-push-action@master
-
       - name: convert tutorials
         run: |
           cd MDtutorials
@@ -52,7 +44,7 @@ jobs:
             [ -d "${path}" ] || continue # skip if not a directory
             dirname="$(basename "${path}")"
             dest="../${dirname}"
-            mkdir ${dest}
+            mkdir -pv ${dest}
             [ ! -d "${path}/data" ] || cp -r "${path}/data" ${dest}/
             [ ! -d "${path}/imgs" ] || cp -r "${path}/imgs" ${dest}/
             cp tutorial.css ${dest}
@@ -64,6 +56,14 @@ jobs:
             done
           done
         
+      - name: build tutorials index 
+        run: |
+          cd scripts
+          python makeGitTutorial.py ..
+      
+#      - name: Push changes
+#        uses: ad-m/github-push-action@master
+
       - name: Sphinx build
         run: |
           sphinx-build webdocs .  # place output into root dir
@@ -78,7 +78,7 @@ jobs:
           mv _gsas2/GSASII/help ./help
       - name: Get rid of the rest of the GSAS-II files & other stuff not needed on web
         run: |
-          rm -rf _gsas2 webdocs scripts
+          rm -rf _gsas2 webdocs scripts MDtutorials
         
       - name: Upload artifact  # creates zip file with website contents
         uses: actions/upload-pages-artifact@v3
diff --git a/MDtutorials/TutorialGuide.txt b/MDtutorials/TutorialGuide.txt
new file mode 100644
index 0000000..2e9d1ff
--- /dev/null
+++ b/MDtutorials/TutorialGuide.txt
@@ -0,0 +1,85 @@
+=====================
+ Quick notes on writing a tutorial
+=====================
+
+New tutorials should be prepared in Markdown rather than HTML if possible. 
+
+* Create a new directory in MDtutorials (./MDtutorials/<newtutorial>) for the
+   tutorial (or combine into an existing directory), 
+
+* Create file for the tutoral as ./MDtutorials/<newtutorial>/<tutorialfile>.md 
+  <newtutorial> and <tutorialfile> will commonly be the same, but need not be so.
+
+  The final tutorial will be placed in
+  https://advancedphotonsource.github.io/GSAS-II-tutorials/<newtutorial>/<tutorialfile>.html
+
+* Images for the tutorial should be placed in subdirectory imgs, ./MDtutorials/<newtutorial>/imgs
+
+* data files needed for the tutorial should be placed in subdirectory ./MDtutorials/<newtutorial>/data
+
+
+The tutorial .md file should start with:
+
+    	         ---
+		 title: "Tutorial: Changing the GSAS-II Font Size"
+		 ---
+		 <!--- Don't change the HTML version of this file; edit the .md version -->
+
+* Sections should be labeled with
+
+  	   ## Intro
+
+   and, subsections with
+
+   	   ### Subsection title
+
+  Sections and subsections will be numbered; subsubsections (etc.) will not be numbered.
+  Place a blank line before and after the section label
+
+
+* For links, use: [displayed text](http://url)
+
+* For figures, which will be sized at 400px max and will be placed at the right margin, use:
+
+      	       ![caption text](imgs/<filename>.png)
+
+   Place a blank line before and after the figure
+
+
+* If needed, where a figure will be sized and placed manually, use HTML directly:
+
+     	     <img src="./imgs/nuc_struct.png" alt="nuclear structure" style="width:500px;">
+
+
+* Equations can be specified with MathJax:
+
+  	    	 Er${}_2$Ge${}_2$O${}_7$
+		 P$4_1 2_1 2$
+
+* Tables can be created using pipe characters
+
+  	 |  `FontSize_incr`  | Example |
+	 | :---: | ------------------------------------- | 
+	 | 0 | ![Example of GSAS-II GUI with the default font size (font=0)](imgs/font0.png) |
+	 | 3 | ![Example of GSAS-II GUI with the font increased by 3 units (font=3)](imgs/font3.png) |
+
+   See markdown docs for other mechanisms to create tables
+
+* To provide a link to a location within the tutorial, define an anchor at the location to be referenced
+
+     	     <a name=myanchor></a>
+
+   then the link to to this will be
+
+   	    here is some text [with a link](#myanchor) provided 
+
+
+* End the document with a table with the date and author(s):
+
+      	  ----
+	  | | 
+	  | ---: |
+	  | Brian Toby |
+	  | January 10, 2025 |
+
+* When the tutorial is complete, update GSASII/tutorialIndex.py to include the new tutorial