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 4b7a57c
Show file tree
Hide file tree
Showing 7 changed files with 82 additions and 82 deletions.
39 changes: 20 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,44 +6,45 @@
# 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:

If you are new to git/github, start [here](https://slaclab.github.io/beamtime-calibration-suite/learning_git/)
If you are new to git/github, start with [Learning Git](https://slaclab.github.io/beamtime-calibration-suite/learning_git/)

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
30 changes: 15 additions & 15 deletions docs/commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
### A) Getting the latest changes for use at a beamtime
```
git fetch
//if beamtime is across multiple days, use 1st day date
//if beamtime is across multiple days, use 1st day's date
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 from the `development` branch:
```
git checkout -b <feature_branch_name> development
```
Expand All @@ -31,29 +31,29 @@ 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
* 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
```
* see list of remote branches (optional)
* see list of remote branches to find the correct branch-name
```
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>
git checkout <other_persons_branch_name>
```

### E) Switching between two branches:
* if the following command lists two branches:
* the following command lists the local branches you can switch to:
```
git branch
```
* you can switch between them with:
* then switch between them with:
```
git checkout <branch_want_to_switch_to>
```
Expand All @@ -63,16 +63,16 @@ 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:
* same syntax as checking-out a branch, but use the tag name instead:
```
git checkout <tag_name>
//ex: 'git checkout v1.0.0'
//ex: git checkout v1.0.0
```
26 changes: 13 additions & 13 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 @@ -9,31 +9,31 @@ Then you can execute the following to setup some project-specific things (must b
```
source setup.sh
```
_(This must be ran in each new terminal session)_
_(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 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
* 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.
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_.
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 All @@ -42,6 +42,6 @@ _(relative or full paths should work)_
You can also set the config-file using the '-cf' or '--configFile' cmd-line arguments
_(note: if set, the environment variable will always override this cmd-line option)_

If neither of the above are set, the suite will try to use a default file named _suiteConfig.py_
If neither of the above are set, the suite will try to use a default file named `suiteConfig.py`

If no config file can be found and read, the library will fail-out early
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 are able to 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.
10 changes: 5 additions & 5 deletions docs/learning_git.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# Learning Git

this project uses _git_ as a version control system, along with the [GitHub](https://github.com/) website for hosting the code and multiple other features
this project uses [git](https://git-scm.com/) as a version control system, along with the [GitHub](https://github.com/) website for hosting the code and multiple other features

if you want a good understanding of git, suggest to read the first 3 chapters of [https://git-scm.com/book/en/v2](https://git-scm.com/book/en/v2):
* the following sections could be skipped: _1.5, 1.6, 2.6, 2.7, 3.5, 3.6_
* the book is a recommended resource by the git community but many other tutorials exist, so feel free to use other 'intro to git/github' videos/websites

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)
21 changes: 11 additions & 10 deletions docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

These steps will get you setup for running and developing the calibration suite!

The steps describe the setup for using the scripts on the [SLAC Shared Scientific Data Facility (S3DF)](https://s3df.slac.stanford.edu/public/doc/#/) A S3DF account is needed before following these steps, and info on how to get one is [here](https://s3df.slac.stanford.edu/public/doc/#/accounts-and-access)
These steps describe the setup for running on the [SLAC Shared Scientific Data Facility (S3DF)](https://s3df.slac.stanford.edu/public/doc/#/) A S3DF account is needed before following these steps, and info on how to get one is [here](https://s3df.slac.stanford.edu/public/doc/#/accounts-and-access)

The only other prerequisites should be a terminal that can run Unix commands (mac and linux have this by default), and basic knowledge of using the terminal!
The only other prerequisites should be a terminal that can run Unix commands (mac and linux have this by default), and basic knowledge of using this terminal

## 1: Make a github.com account

* 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 @@ -29,8 +29,8 @@ The only other prerequisites should be a terminal that can run Unix commands (ma

## 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 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 All @@ -54,6 +54,7 @@ git config --global core.editor emacs

* first make sure you are logged into your github account in your web browser
* for the next two bullet-points, make sure you have selected the 'Linux' tab near the top of the page, not 'Mac'!
* note: the commands on the following pages have to be ran in the terminal setup in step **4)**, which is ssh'd into S3DF
* Follow instructions under “Generating a new SSH key” and “Adding your SSH key to the ssh-agent”: [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key)
* Follow instructions under “Adding a new SSH key to your account”: [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account)

Expand All @@ -70,12 +71,12 @@ git clone [email protected]:slaclab/beamtime-calibration-suite.git
cd beamtime-calibration-suite
git switch development
ls
//should see a bunch of folders!
//should see a bunch of folders
cd suite_scripts
ls
//now should see a bunch of python scripts!
//now should see a bunch of python scripts
```
* if an error occurs during these commands, SSH setup in step **6)** may have had an issue and might need to be debugged
* if an error occurs with these commands, SSH setup in step **6)** may have had an issue and might need to be debugged


## 8: Run an example script
Expand All @@ -88,7 +89,7 @@ source setup.sh
mkdir setup_test_output
cd suite_scripts
//'OUTPUT_ROOT=' sets the OUTPUT_ROOT environment var to an empty value,
//which causes the script to look relative to the current directory for the output folder
//which makes the script to look relative to the current directory for the output-folder
OUTPUT_ROOT= python EventScanParallelSlice.py -r 457 -p ../setup_test_output
//let the script run to completion...
ls -lt ../setup_test_output
Expand Down
Loading

0 comments on commit 4b7a57c

Please sign in to comment.