Skip to content

Commit 330d6de

Browse files
briantobybriantoby
committed
add draft MarkDown help & manual build
1 parent 3747458 commit 330d6de

29 files changed

+2582
-0
lines changed

‎.github/workflows/test_builddocsite.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# create a documentation web site for GSAS-II from four sources
2+
# * HTML tutorials are simply copied
3+
# * markdown tutorials (in ./MDtutorials) are formatted with pandoc and are copied over
4+
# * HTML help files are copied over from the GSAS-II sources
5+
# * sphinx is used to generate HTML from files in ./webdocs
6+
7+
# Also the tutorials.html file and the */data/index.html files are
8+
# created by running scripts/makeGitTutorial
9+
10+
# this is a test version that creates draft help pages from the MDhelp directory
11+
12+
name: build GSAS-II web site
13+
14+
on: [workflow_dispatch]
15+
#on: [push, workflow_dispatch]
16+
17+
permissions:
18+
contents: write
19+
id-token: write
20+
pages: write
21+
22+
jobs:
23+
build: # Build web pages
24+
runs-on: ubuntu-latest
25+
steps:
26+
27+
- name: Python setup
28+
uses: actions/setup-python@v3
29+
- name: Sphinx setup
30+
run: |
31+
pip install sphinx sphinx_readable_theme
32+
- name: pandoc setup
33+
uses: pandoc/actions/setup@v1
34+
- name: mkdocs setup
35+
run: |
36+
pip install mkdocs
37+
38+
- name: Checkout
39+
uses: actions/checkout@v4
40+
41+
- name: convert MDhelp
42+
run: |
43+
cd MDhelp
44+
mkdocs build
45+
cp -vr site ../help_test
46+
47+
- name: Get tutorials index from source code
48+
run: |
49+
curl -L https://github.com/AdvancedPhotonSource/GSAS-II/raw/master/GSASII/tutorialIndex.py -o scripts/tutorialIndex.py
50+
51+
- name: convert tutorials
52+
run: |
53+
cd MDtutorials
54+
for path in ./*; do
55+
[ -d "${path}" ] || continue # skip if not a directory
56+
dirname="$(basename "${path}")"
57+
dest="../${dirname}"
58+
mkdir -pv ${dest}
59+
[ ! -d "${path}/data" ] || cp -r "${path}/data" ${dest}/
60+
[ ! -d "${path}/imgs" ] || cp -r "${path}/imgs" ${dest}/
61+
cp tutorial.css ${dest}
62+
for fil in $dirname/*.md; do
63+
outfile="${dest}/$(basename "${fil%.md}.html")"
64+
echo "creating $outfile from $fil"
65+
pandoc --standalone ${fil} --css tutorial.css -o ${outfile}
66+
sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
67+
done
68+
git add ${dest}
69+
done
70+
cd ..
71+
72+
- name: build tutorials index
73+
run: |
74+
cd scripts
75+
python makeGitTutorial.py ..
76+
77+
# - name: Note changed files
78+
# run: |
79+
# git add tutorials.html
80+
# git add */data/index.html
81+
# git status
82+
# git commit -m"changes from automated build of tutorials"
83+
# - name: Push changes
84+
# uses: ad-m/github-push-action@master
85+
86+
- name: Sphinx build
87+
run: |
88+
sphinx-build webdocs . # place output into root dir
89+
cp webdocs/_static/fix.css _static/fix.css # should be done by sphinx
90+
91+
# get the help pages from the GSAS-II sources into the web site
92+
- name: Get GSAS-II
93+
run: |
94+
git clone --depth 1 https://github.com/AdvancedPhotonSource/GSAS-II.git _gsas2
95+
- name: move help into site
96+
run: |
97+
mv _gsas2/GSASII/help ./help
98+
- name: Get rid of the rest of the GSAS-II files & other stuff not needed on web
99+
run: |
100+
rm -rf _gsas2 webdocs scripts MDtutorials
101+
102+
- name: Upload artifact # creates zip file with website contents
103+
uses: actions/upload-pages-artifact@v3
104+
with:
105+
path: .
106+
name: github-pages
107+
retention-days: 1
108+
109+
deploy: # Deployment of web pages to GitHub pages
110+
needs: build
111+
permissions:
112+
pages: write
113+
id-token: write
114+
environment:
115+
name: github-pages
116+
url: ${{ steps.deployment.outputs.page_url }}
117+
runs-on: ubuntu-latest
118+
119+
steps:
120+
- name: Deploy to GitHub Pages
121+
id: deployment
122+
uses: actions/deploy-pages@v4
123+
with:
124+
token: ${{ secrets.GITHUB_TOKEN }}
125+
artifact_name: github-pages

‎MDhelp/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
This directory contains a draft version of the GSAS-II help pages
2+
that are being converted from their MS-Word/HTML format into
3+
MarkDown where web pages are generated with mkdocs
4+
5+
Status of work 7/16/2025:
6+
7+
These files have been revised, but need another pass to update #TBD
8+
links once the anchors have been defined. There might be a few
9+
additional links that need to be added:
10+
11+
44 docs/index.md
12+
14 docs/preface.md
13+
60 docs/applicationwindow.md
14+
191 docs/mainmenu.md
15+
95 docs/others.md
16+
17+
These files have had only minor editing. A few need to be broken up:
18+
19+
170 docs/cluster.md
20+
157 docs/datatree.md
21+
445 docs/histgramtree.md
22+
154 docs/image.md
23+
59 docs/pairdistribution.md
24+
629 docs/phase.md
25+
74 docs/powderpeak.md
26+
89 docs/reflectometry.md
27+
62 docs/sequential.md
28+
39 docs/singlecrystal.md
29+
94 docs/smallanglescattering.md

‎MDhelp/docs/applicationwindow.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# GSAS-II GUI Organization
2+
3+
The GSAS-II GUI uses three windows, which are described below. The main window has two parts. To the left is the "Data Tree" and to the right is the "Data Window". A second window, called the "Plots Window" is used for graphics such as plots of data or display of three-dimensional structures. The third window, the Console window, is used to show output from the program.
4+
5+
<a name="Data_tree"></a>
6+
## GSAS-II Data Tree
7+
8+
The data tree shows contents of a GSAS-II project (which can be read or saved as a .gpx file) in a hierarchical view. Clicking on any item in the tree opens that information on the right side of the window in the "Data Editing" section, where information in that item can be viewed or edited. For example, the "[Sample Parameters](#TBD)" item under a 'PWDR’ entry contains information about how data were collected, such as the sample temperature. The arrow keys (up & down) move the selection to successive entries in the data tree; both the data window and the associated plot (if any) will change.
9+
10+
<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
11+
12+
The leftmost entries in the GSAS-II menu provide access to many features of GSAS-II. Other menu items will change depending on what type of entry is selected in the data tree. The menu commands that do not change and are described in the [main menu commands](#TBD) section.
13+
14+
<a name="Data_frame"></a>
15+
## GSAS-II Data Window
16+
17+
Different information is displayed in the Data Editing Window, depending on which section of the [data tree](#Data_tree) is selected. For example, clicking on the "Notebook" entry of the data tree brings up the [Notebook editing window](#TBD), as documented elsewhere.
18+
19+
<a name="Plots"></a>
20+
## GSAS-II Plots Window
21+
22+
This window presents all the graphical material as a multipage tabbed set of plots utilizing the matplotlib python package. Each page containing a graph or plot has a tool bar with these controls:
23+
24+
![Toolbar](./images/toolbar.png)
25+
26+
The first eight icons have the following functions: **Home**, **Back**, **Forward**, **Pan**, **Zoom**, **Save**, **Key Press** and **Help**, respectively and are described below. The remainder (yellow arrows) move or rescale the plot. The last "P" allows preparation of a publication quality plot. The meaning of these icons are as follows:
27+
28+
* **Home** - returns the plot to the initial view/scaling
29+
* **Back** - returns the plot to the previous view/scaling
30+
* **Forward** - reverses the action in the previous press(es) of the Back button
31+
* **Pan** - allows you to control panning across the plot (press left mouse button & drag) and zooming (press right mouse button & drag),
32+
* **Zoom** - allows you to select a portion of the plot (press left mouse button & drag for zoom box) for the next plot.
33+
* **Save** - allows you to save the currently displayed plot in one of several graphical formats suitable for printing or insertion in a document.
34+
* <img src="./images/KeyPress.png" width="20" height="20"> -
35+
Shows a menu of key press commands that can be used to interact with the plot. These actions can be initiated from the menu.
36+
* <img src="./images/grHelp.png" width="20" height="20"> -
37+
accesses GSASII help on the specific plot type.
38+
* "<" - Shifts the plot to the left, relative to the axes
39+
* ">" - Shifts the plot to the right, relative to the axes
40+
* "^" - Shifts the plot up, relative to the axes
41+
* "v" - Shifts the plot down, relative to the axes
42+
* "<>" - Zooms in on the plot (magnifies) along the horizontal (x) direction to show more details.
43+
* "><" - Zooms out on the plot (demagnifies) along the horizontal (x) direction.
44+
* <img src="./images/vmag.png" width="20" height="20"> -
45+
Zooms in on the plot (magnifies) along the vertical (y) direction to show more details.
46+
* <img src="./images/dmag.png" width="20" height="20"> -
47+
Zooms out on the plot (demagnifies) along the vertical (y) direction.
48+
* <img src="./images/Publish.png" width="20" height="20"> -
49+
prepare a fancy publishable version of the current plot (PWDR plots only)
50+
51+
For 3-dimensional structure drawings there will be below the toolbar may be a status bar that on the left may show either an instruction for a keyed input or a pull down selection of keyed input; on the right may be displayed position dependent information that is updated as the mouse is moved over the plot region.
52+
53+
<a name="Console"></a>
54+
## GSAS-II Console Window
55+
56+
This is a "terminal" or "cmd.exe" window that shows simple text. It is used for output from the program and in some cases error messages may appear here.
57+
58+
<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
59+
60+
You can never type anything into this window. It is for output from GSAS-II only. If something is not working properly, you may find some useful information here. Please do include the contents of this window when reporting a bug.

0 commit comments

Comments
 (0)