From 4b7a57c1be15240c176b04468ad59013b7fa74c2 Mon Sep 17 00:00:00 2001 From: nstelter-slac Date: Mon, 25 Mar 2024 14:43:00 -0700 Subject: [PATCH] DOCS: trying to get docs formatting fixed --- README.md | 39 ++++++++++++++++++++------------------- docs/commands.md | 30 +++++++++++++++--------------- docs/environment.md | 26 +++++++++++++------------- docs/index.md | 6 +++--- docs/learning_git.md | 10 +++++----- docs/setup.md | 21 +++++++++++---------- docs/workflow.md | 32 +++++++++++++++----------------- 7 files changed, 82 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 101dedd..125b853 100644 --- a/README.md +++ b/README.md @@ -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)_ - -_(note: in the 1st command: replace \ with your slac linux-username)_ + -_(note: lines starting with '//' are comments with explanation and don't need to be ran)_ + -_(note: in the 1st command: replace \ with your slac linux-username)_ ``` -# ssh into the s3df machines +// ssh into the s3df machines ssh -Yt @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 git@github.com: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 \ No newline at end of file +For commit messages, we can try to follow the PyDM guidelines: https://slaclab.github.io/pydm/development/development.html#commit-guidelines diff --git a/docs/commands.md b/docs/commands.md index c8f20e7..55f54ec 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -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___ ``` -### B) Getting the latest changes from the _development_ branch +### B) Getting the latest changes from the `development` branch ``` git pull origin development ``` @@ -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 development ``` @@ -31,29 +31,29 @@ git commit -m ``` git push origin ``` -* 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 +git checkout ``` ### 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 ``` @@ -63,16 +63,16 @@ git checkout * 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 -//ex: 'git checkout v1.0.0' +//ex: git checkout v1.0.0 ``` \ No newline at end of file diff --git a/docs/environment.md b/docs/environment.md index 5355c75..749ffc1 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -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 ``` @@ -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 \_ cmdline arg. +The output-directory can be set using the `-p ` 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" ``` @@ -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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 1018175..1291a54 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 * @@ -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. diff --git a/docs/learning_git.md b/docs/learning_git.md index 8584a10..586a9fa 100644 --- a/docs/learning_git.md +++ b/docs/learning_git.md @@ -1,6 +1,6 @@ # 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_ @@ -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 \ No newline at end of file +for commit messages, we can try to follow the PyDM [guidelines](https://slaclab.github.io/pydm/development/development.html#commit-guidelines) \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index c44d918..7424637 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -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 _\-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 `-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 @@ -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 _\_ 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 `` with your slac unix account-name) ``` ssh -Yt @s3dflogin.slac.stanford.edu //now enter your info to login to s3df... @@ -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) @@ -70,12 +71,12 @@ git clone git@github.com: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 @@ -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 diff --git a/docs/workflow.md b/docs/workflow.md index e8392bd..32d7a1b 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -1,21 +1,19 @@ # 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\_\\_\\_\_ 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_\_\_\_ 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____` 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___` 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___ @@ -23,7 +21,7 @@ git push origin beamtime___ ``` ### 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___ @@ -46,8 +44,8 @@ git pull ``` ### After Beamtime: -* make sure all the changes that need to be saved are commited to _beamtime\_\_\__ -* use a pull request to merge _beamtime\_\_\__ into _main_ +* make sure all the changes that need to be saved are commited to `beamtime___` +* use a pull request to merge `beamtime___` 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 @@ -56,5 +54,5 @@ git tag v -a //an example tag number would be 1.0.3 //the description should be 'Beamtime ' //(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 \ No newline at end of file