Merge pull request #212 from AdvancedPhotonSource/newhelp

Implement MarkDown-generated Help

Author: briantoby

.github/workflows/update_help_test.yml

@@ -0,0 +1,70 @@
+name: xfer help info from GSAS-II docs repo
+
+on:
+  workflow_dispatch:
+  
+  push:
+    branches:  
+      - newhelp
+
+permissions:
+  contents: write
+  id-token: write
+  pages: write
+
+jobs:
+  build:       # Build web pages
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Python setup
+        uses: actions/setup-python@v3
+
+      - name: mkdocs setup
+        run: |
+          pip install mkdocs mkdocs-material python-markdown-math mkdocs-static-i18n
+          pip install mkdocs-to-pdf pymdown-extensions
+
+      # get the new help pages from GSAS-II docs
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+            repository: AdvancedPhotonSource/GSAS-II-tutorials.git
+            path: _docs
+            ref: newhelp
+#            token: ''
+
+      # MD help conversion
+      - name: convert MDhelp
+        run: |
+          pwd
+          cd _docs/MDhelp
+          mkdocs build
+          python findMDanchors.py  # create an anchor index
+          rm -rf ../../GSASII/help/assets/javascripts/
+          rm -rf ../../GSASII/help/assets/stylesheets/
+          cp -vr site/* ../../GSASII/help
+
+      - name: git diagnostics
+        run: |
+          pwd 
+          git status
+          git diff
+          git add GSASII/help
+          echo "After add"
+          git status
+
+      - name: commit changes
+        run: |
+          pwd 
+          git add GSASII/help
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m"update help files"
+
+      - name: push help into repo
+        run: |
+          git push

GSASII/GSASIIctrlGUI.py

@@ -5900,13 +5900,13 @@ def __init__(self,frame,includeTree=False,morehelpitems=[]):
             helpobj = self.Append(wx.ID_ANY,lbl,'')
             frame.Bind(wx.EVT_MENU, self.OnHelpById, helpobj)
             self.HelpById[helpobj.GetId()] = indx
-        # add help lookup(s) in gsasii.html
+        # add help lookup(s) in GSAS-II Help
         self.AppendSeparator()
         if includeTree:
             helpobj = self.Append(wx.ID_ANY,'Help on GSAS-II',
-                'Access web page with information on GSAS-II')
+                'Access web pages with information on GSAS-II')
             frame.Bind(wx.EVT_MENU, self.OnHelpById, id=helpobj.GetId())
-            self.HelpById[helpobj.GetId()] = 'Data tree'
+            self.HelpById[helpobj.GetId()] = 'HelpIntro'
         helpobj = self.Append(wx.ID_ANY,'Help on current data tree item\tF1',
                 'Access web page on selected item in tree')
         frame.Bind(wx.EVT_MENU, self.OnHelpById, id=helpobj.GetId())
@@ -5916,21 +5916,18 @@ def __init__(self,frame,includeTree=False,morehelpitems=[]):
 
     def OnHelpById(self,event):
         '''Called when Help on... is pressed in a menu. Brings up a web page
-        for documentation. Uses the helpKey value from the dataWindow window
-        unless a special help key value has been defined for this menu id in
-        self.HelpById
-
-        Note that self should now (2frame) be child of the main window (G2frame)
+        for documentation. Uses the G2frame.dataWindow.helpKey value to select
+        what help is shown, unless a special help key value has been defined 
+        for the calling menu id (via a lookup in self.HelpById[], which is used
+        for Tutorials & Overall help). 
+        Note that G2frame.dataWindow.helpKey SelectDataTreeItem and reflects 
+        the data tree item that has been selected.
+
+        Note that self here should be a child of the main window (G2frame)
+        where self.frame is G2frame
         '''
-        if hasattr(self.frame,'dataWindow'):  # Debug code: check this is called from menu in G2frame
-            # should always be true in 2 Frame version
-            dW = self.frame.dataWindow
-        else:
-            print('help error: not called from standard menu?')
-            print (self)
-            return
         try:
-            helpKey = dW.helpKey # look up help from helpKey in data window
+            helpKey = self.frame.dataWindow.helpKey # look up help from helpKey in data window
             #if GSASIIpath.GetConfigValue('debug'): print 'DBG_dataWindow help: key=',helpKey
         except AttributeError:
             helpKey = ''
@@ -6035,7 +6032,7 @@ def copy2clip(event):
 class HelpButton(wx.Button):
     '''Create a help button that displays help information.
     The text can be displayed in a modal message window or it can be
-    a reference to a location in the gsasII.html (etc.) help web page, in which
+    a reference to a location in the gsasII help web pages, in which
     case that page is opened in a web browser.
 
     TODO: it might be nice if it were non-modal: e.g. it stays around until
@@ -6046,9 +6043,12 @@ class HelpButton(wx.Button):
     :param str msg: the help text to be displayed. Indentation on
        multiline help text is stripped (see :func:`StripIndents`). If wrap
        is set as non-zero, all new lines are
-    :param str helpIndex: location of the help information in the gsasII.html
-      help file in the form of an anchor string. The URL will be
-      constructed from: location + gsasII.html + "#" + helpIndex
+    :param str helpIndex: selection for the help information in the GSAS-II
+      help files, in the form of an anchor string. That anchor is looked 
+      up to find the file name and the URL is constructed from: 
+
+         <location> + <filename> + "#" + helpIndex
+
     :param int wrap: if specified, the text displayed is reformatted by
       wrapping it to fit in wrap pixels. Default is None which prevents
       wrapping.
@@ -7626,22 +7626,31 @@ class G2LstCtrl(wx.ListCtrl):
 htmlPanel = None
 htmlFrame = None
 htmlFirstUse = True
-#helpLocDict = {}  # to be implemented if we ever split gsasii.html over multiple files
+helpLocDict = {}
+'This is an index to the HTML anchors defined in the GSAS-II help files'
 path2GSAS2 = os.path.dirname(os.path.realpath(__file__)) # save location of this file
 def ShowHelp(helpType,frame,helpMode=None):
     '''Called to bring up a web page for documentation.'''
     global htmlFirstUse,htmlPanel,htmlFrame
+    if not helpLocDict: # load the anchor index
+        indx = os.path.abspath(os.path.join(path2GSAS2,'help','anchorIndex.txt'))
+        print('reading file',indx)
+        with open(indx,'r') as indexfile:
+            for line in indexfile.readlines():
+                fil,anchors = line.split(':')
+                for a in anchors.split(','):
+                    #if a in helpLocDict: print(a,'repeated!')
+                    helpLocDict[a.strip()] = fil
     # no defined link to use, create a default based on key
-    if helpType.lower().startswith('pwdr'):
-        helplink = 'gsasII-pwdr.html#'+helpType.replace(')','').replace('(','_').replace(' ','_')
-    elif helpType.lower().startswith('phase'):
-        helplink = 'gsasII-phase.html#'+helpType.replace(')','').replace('(','_').replace(' ','_')
-    elif helpType.lower().startswith('hist/phase'):
-        helplink = 'gsasII-phase.html#Phase-Data'
-    elif helpType:
-        helplink = 'gsasII.html#'+helpType.replace(')','').replace('(','_').replace(' ','_')
-    else:
-        helplink = 'gsasII.html'
+    helplink = 'index.html'
+    if helpType:
+        anchor = helpType.replace(')','').replace('(','_').replace(' ','_')
+        if anchor not in helpLocDict:
+            print(f'Help lookup problem, anchor {anchor} not found'
+                      '\nPlease report this to [email protected] along with a'
+                      '\nscreen image showing where you tried to get help')
+        else:
+            helplink = f'{helpLocDict[anchor]}#{anchor}'
     # determine if a web browser or the internal viewer should be used for help info
     if helpMode:
         pass

GSASII/GSASIIdataGUI.py

@@ -8564,7 +8564,7 @@ def OnShowShift(event):
     parentID = G2frame.root
     if item == G2frame.root:
         G2frame.dataWindow.ClearData()
-        G2frame.helpKey = "Data tree"
+        G2frame.dataWindow.helpKey = "Data tree"
         mainSizer =  wx.BoxSizer(wx.VERTICAL)
         G2frame.dataWindow.SetSizer(mainSizer)
         mainSizer.Add(wx.StaticText(G2frame.dataWindow, wx.ID_ANY,

GSASII/GSASIIplot.py

@@ -463,7 +463,7 @@ def FindPlotTab(self,label,Type,newImage=True,publish=None):
         try:
             Page.helpKey = self.G2frame.dataWindow.helpKey
         except AttributeError:
-            Page.helpKey = 'Data tree'
+            Page.helpKey = 'HelpIntro'
         return new,plotNum,Page,Plot,limits
 
     def _addPage(self,name,page):