Skip to content

Commit

Permalink
DOCS: trying to get docs formatting fixed
Browse files Browse the repository at this point in the history
  • Loading branch information
@nstelter-slac
nstelter-slac committed Mar 25, 2024
1 parent aeeb248 commit 3e9304f
Show file tree
Hide file tree
Showing 7 changed files with 63 additions and 64 deletions.
37 changes: 19 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,39 @@
# Step-by-step to get running quick!
* First, follow steps **1** through **7**: [Github and Git Setup](https://slaclab.github.io/beamtime-calibration-suite/setup/)
* Next, run the following commands in a terminal (linux or mac terminal should work):
 -_(note: lines starting with '#' are comments with explanation and don't need to be ran)_
&emsp;-_(note: in the 1st command: replace \<slac-username> with your slac linux-username)_
&emsp;-_(note: lines starting with '//' are comments with explanation and don't need to be ran)_
&emsp;-_(note: in the 1st command: replace \<slac-username> with your slac linux-username)_
```
# ssh into the s3df machines
// ssh into the s3df machines
ssh -Yt <slac-username>@s3dflogin.slac.stanford.edu
ssh psana
# do setup for s3df environment
// do setup for s3df environment
source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh
# download the code
// download the code
mkdir repos && cd repos
git clone [email protected]:slaclab/beamtime-calibration-suite.git
cd beamtime-calibration-suite
git fetch
git switch development
# do more environment setup for suite-scripts
// do more environment setup for suite-scripts
source setup.sh
# run an example script
// setup for running an example script
mkdir setup_test_output
cd suite_scripts
python EventScanParallel.py -r 457
```
If everything is working, the script should start spitting terminal-output like:
```
...
3259 True
3257 True
3256 True
3260 True
Event number foo
// run an example script
OUTPUT_ROOT= python EventScanParallelSlice.py -r 457 -p ../setup_test_output
//let the script run to completion...
// now check the example ran correctly
ls ../setup_test_output
//if things are working correctly, you should see these non-empty files:
eventNumbers_c0_r457_rixx1003721.npy means_c0_r457_rixx1003721.npy
EventScanParallel_c0_r457_n1.h5
```

## Developers:
Expand All @@ -46,4 +47,4 @@ If you are new to git/github, start [here](https://slaclab.github.io/beamtime-ca

An overview of the development process is found [here](https://slaclab.github.io/beamtime-calibration-suite/workflow/)

For commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines
For commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines
16 changes: 8 additions & 8 deletions docs/commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ git fetch
git switch beamtime_<month>_<day>_<year>
```

### B) Getting the latest changes from the _development_ branch
### B) Getting the latest changes from the `development` branch
```
git pull origin development
```
Expand All @@ -17,7 +17,7 @@ git pull origin development
```
git pull origin development
```
* make a branch for your feature off of the _development_ branch:
* make a branch for your feature off of the `development` branch:
```
git checkout -b <feature_branch_name> development
```
Expand All @@ -31,10 +31,10 @@ git commit -m <commit-message>
```
git push origin <feature_branch_name>
```
* if want to merge your changes into the _development_ branch (and keep them long-term)
* follow **F)** and make a pull-request from your feature-branch into _development_
* if want to merge your changes into the `development` branch (and keep them long-term)
* follow **F)** and make a pull-request from your feature-branch into `development`

### D) If pulling down someone else's branch (non main/development branch):
### D) pulling down someone else's branch (non main/development branch):
* get updated branch info from remote
```
git fetch origin
Expand All @@ -43,7 +43,7 @@ git fetch origin
```
git branch -r
```
* checkout their branch (use the branch name without the 'oriogin/' prefix)
* checkout their branch (use the branch name without the 'origin/' prefix)
```
git checkout <other_person_branch_name>
```
Expand All @@ -63,13 +63,13 @@ git checkout <branch_want_to_switch_to>
* click green 'New pull request' button in upper right
* you will see two grey boxes containing branch names and an arrow pointing from one box to the other
* the "compare: ..." box is the branch that will get merged into the "base: ..." box's branch
* the base should be the branch named _development_
* the base should be the branch named `development`
* once the grey boxes are set correctly, click the green 'Create pull request' button
* once branch is ready to merge, you can click the ''Merge pull request' button to merge the commit
* being ready means: potentially reviewed (if big change), passing any automated checks/tests, etc
* if github is not allowing the merge automatically, you will need to merge or rebase locally and manually handle the conflicts

### G) Check out tagged commit (old beamtime code is tagged):
### G) Check out tagged commit (old beamtime code will be tagged):

* same syntax as checking-out a branch, but use tag name instead:
```
Expand Down
18 changes: 9 additions & 9 deletions docs/environment.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Setup Environment

When running on S3DF, you will first need to setup your environment so you can run _python_, _psana_, and other need programs:
When running on S3DF, you will first need to setup your environment for _python_, libraries like _psana_, etc:
```
source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh
```
Expand All @@ -11,29 +11,29 @@ source setup.sh
```
_(This must be ran in each new terminal session)_

This script simplifies setting up the terminal environment and will be all that most script users will need to do
This script simplifies setting up the terminal environment and should be all the environment setup most users will need to do

This script does the following:
* appends your cloned location of this library to your _PYTHONPATH_, so scripts in _/suite_scripts_ and other locations on your machine can find the library code
* sets the library's output-root to the shared /rix dir used for the current experiment
* sets the config file to the currently used _rixSuiteConfig.py_ file
* appends your cloned location of this library to your _PYTHONPATH_, so scripts in _/suite_scripts_ and other locations on your machine can find the library code
* sets the library's output-root to the shared /rix dir used for the current experiment git
* sets the config file to the currently used _rixSuiteConfig.py_ file

The rest of the page has more detail on configuring the scripts.

### Specify Output Root
### Specifying Output Root

The output-root determines where the library will look for an output folder.

For example, if the root is set to the default value _/sdf/data/lcls/ds/rix/rixx1003721/results/scripts/_, the library will look for an output dir _../scan_ in the location _/sdf/data/lcls/ds/rix/rixx1003721/results/scripts/../scan_.

The output-directory can be set using the _-p \<dir_name>_ cmdline arg.
The output-directory can be set using the _-p <dir_name\>_ cmdline arg.

Setting the var to nothing (_export OUTPUT_ROOT=_) will have the library look for an output folder relative to the location of the current script being ran
Setting the var to nothing (_export OUTPUT_ROOT=_ ) will have the library look for an output folder relative to the location of the current script being ran


### Point to Config File

Specify which config file for the library to use by setting the 'SUITE_CONFIG' environment variable:
Specify which config file for the library to use by setting the _SUITE_CONFIG_ environment variable:
```
export SUITE_CONFIG="rixSuiteConfig.py"
```
Expand Down
6 changes: 3 additions & 3 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Some more general info can be found on the team's confluence page: [https://conf

The following describes what and where things are:

* /calibrationSuite: The library code lives here, and the functions can be imported into other scripts as such:
* _/calibrationSuite_: The library code lives here, and the functions can be imported into other scripts as such:
```
from calibrationSuite.basicSuiteScript import *
from calibrationSuite.fitFunctions import *
Expand All @@ -26,5 +26,5 @@ _(documentation on the library functionality is still to come, but example usage

### Important branches:

* _development_: contains the newest 'good' code, usually has new changes and bug fixes.
* _main_: stable code that's used during beamtimes. The code from each beamtime (including the changes made during) is tagged.
* `development`: contains the newest 'good' code, usually has new changes and bug fixes.
* `main`: stable code that's used during beamtimes. The code from each beamtime (including the changes made during) is tagged.
8 changes: 4 additions & 4 deletions docs/learning_git.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ if you want a good understanding of git, suggest to read the first 3 chapters of

short presentation that summaries the book's content can be found [here](https://courses.cs.washington.edu/courses/cse403/13au/lectures/git.ppt.pdf)

presentation by SLAC that explains git, github, git workflow, etc can be found [here](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7)
presentation from SLAC that explains git, github, git workflow, etc can be found [here](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7)

git commands cheat-sheet can be found here [here](https://www.jrebel.com/system/files/git-cheat-sheet.pdf) (**link will start download of pdf cheat sheet)
git commands cheat-sheet can be found [here](https://www.jrebel.com/system/files/git-cheat-sheet.pdf) (**link will start download of pdf cheat sheet)

(if you plan on developing the library) read about GitHub's 'Pull Request' feature here [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
(if you plan on developing the library) read about GitHub's 'Pull Request' feature [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)

for commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines
for commit messages, we can try to follow the PyDM [guidelines](https://slaclab.github.io/pydm/development/development.html#commit-guidelines)
10 changes: 5 additions & 5 deletions docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ The only other prerequisites should be a terminal that can run Unix commands (ma

* if you already have github account and want to use it, skip to step **2)**
* else to make a new account following the steps here: [https://github.com/join](https://github.com/join)
* your username can be anything, some people like to use the _\<username>-slac_ convention (ex: _nstelter-slac_)
* for the email you can use your _@slac.stanford.edu_ address or any other address if you want (just make sure to use the same email in step **4)**
* your username can be anything, some people like to use the _<username\>-slac_ convention (ex: _nstelter-slac_)
* for the email you can use your _@slac.stanford.edu_ address or any other address if you want (just make sure to use the same email in step **5)**
* you will need a code from your email when creating the account

## 2: Register your github account with ‘SLAC Lab’ github group
Expand All @@ -25,12 +25,12 @@ The only other prerequisites should be a terminal that can run Unix commands (ma

* after completing step **2)**, your github account should now be a member of the 'SLAC Lab' github group
* now go to [https://github.com/orgs/slaclab/teams/beamtime_calibration_suite_devs](https://github.com/orgs/slaclab/teams/beamtime_calibration_suite_devs) and click the 'Request to join' button towards the upper-right of the page
* this will grant you write access to the repository (used for development and sharing code-changes during beamtime)
* this will grant you write access to the repository (used for development and sharing codappe-changes during beamtime)

## 4: Setup your terminal for next steps

* for the following steps **5)**, **6)**, **7)**: make sure you terminal (linux or mac) is setup first with the following commands:
(note: in the 1st command replace _\<slac-username\>_ with your slac unix account-name)
* for the following steps **5)**, **6)**, **7)**, **8)**, make sure you terminal (linux or mac) is setup first with the following commands:
(note: in the 1st command replace _<slac-username\>_ with your slac unix account-name)
```
ssh -Yt <slac-username>@s3dflogin.slac.stanford.edu
//now enter your info to login to s3df...
Expand Down
32 changes: 15 additions & 17 deletions docs/workflow.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,27 @@
# Git/GitHub Workflow

We should try to generally follow the branching and pull-request workflow described in this [presentation](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7)
* in our case the two important branches will be _main_ and _development_
* in-between beamtimes, _development_ is used for pushing work
* right before beamtimes, _development_ is merged into _main_
* then a branch named _beamtime\_\<month>\_\<day>\_<year>\_ is branched off main
* this branch is used for sharing code fixes/changes (pushing-to and pulling-from) during beamtime
* after beamtimes, we merge _beamtime_\<month>_\<day>_\<year>_ back into _main_ and tag it

(img: https://www.pablogonzalez.io/salesforce-git-branching-strategies/)
we should try to generally follow the branching and pull-request workflow described in this SLAC [presentation](https://docs.google.com/presentation/d/1AXcH17xDfum4mZsdV5lfjn_mvSMp2ye796xrVuSM3w8/edit#slide=id.gf4dca9affc_0_7)
* in our case the two important branches will be `main` and `development`
* in-between beamtimes, `development` is used for pushing work
* right before beamtimes, `development` is merged into `main`
* then a branch named `beamtime_<month>_<day>_<year>_` is branched off main
* this branch is used for sharing code fixes/changes (pushing-to and pulling-from) during beamtime
* after beamtimes, we merge `beamtime_<month>_<day>_<year>` back into `main` and tag it

### Before Beamtime:
* checkout _development_ (or a earlier stable point of _development_)
* checkout `development` (or a earlier stable point of `development`)
* manually run and check the output of script planned for use on the beamtime, as a final sanity check
* use a pull request to merge _development_ into _main_
* to do this follow the instructions in section **F)** of [https://slaclab.github.io/beamtime-calibration-suite/commands/](https://slaclab.github.io/beamtime-calibration-suite/commands/)
* _main_ is safeguarded and will require a +1 from another developer
* use a pull request to merge `development` into `main`
* to do this follow the instructions in section **F)** of the doc page [Git Commands for Common Tasks](https://slaclab.github.io/beamtime-calibration-suite/commands/)
* `main` is safeguarded and will require a +1 from another developer
* make a branch for work during this specific beamtime
```
git checkout -b main beamtime_<month>_<day>_<year>
git push origin beamtime_<month>_<day>_<year>
```

### During Beamtime:
* At start of beamtime, everyone needs to download the branch for this beamtime:
* at start of beamtime, everyone needs to download the branch for this beamtime:
```
git fetch
git switch beamtime_<month>_<day>_<year>
Expand All @@ -46,8 +44,8 @@ git pull
```

### After Beamtime:
* make sure all the changes that need to be saved are commited to _beamtime\_<month>\_<day>\_<year>_
* use a pull request to merge _beamtime\_<month>\_<day>\_<year>_ into _main_
* make sure all the changes that need to be saved are commited to `beamtime_<month>_<day>_<year>_`
* use a pull request to merge `_beamtime_<month>_<day>_<year>_` into `main`
* add a tag for the beamtime
```
//tag number is arbitrary at this point, just look at last tag and increment one of the values
Expand All @@ -56,5 +54,5 @@ git tag v<tag number> -a //an example tag number would be 1.0.3
//the description should be 'Beamtime <Month> <Day> <Year>'
//(if beamtime is multiple days, use the 1st day's date)
```
* use a pull request to merge _main_ into _development_
* use a pull request to merge _main_ into `development`
* this is kinda sloppy, but seems like easiest way to 'reset' things after beamtime

0 comments on commit 3e9304f

Please sign in to comment.