From 3e9304f1793b81163db9f7d01597393a19cf6bc9 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 | 37 +++++++++++++++++++------------------ docs/commands.md | 16 ++++++++-------- docs/environment.md | 18 +++++++++--------- docs/index.md | 6 +++--- docs/learning_git.md | 8 ++++---- docs/setup.md | 10 +++++----- docs/workflow.md | 32 +++++++++++++++----------------- 7 files changed, 63 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 101dedd..527e467 100644 --- a/README.md +++ b/README.md @@ -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)_ - -_(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: @@ -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 \ 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..e51cc44 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -7,7 +7,7 @@ git fetch 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 off of the `development` branch: ``` git checkout -b development ``` @@ -31,10 +31,10 @@ 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 (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 @@ -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 ``` @@ -63,13 +63,13 @@ 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: ``` diff --git a/docs/environment.md b/docs/environment.md index 5355c75..714c7f6 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 ``` @@ -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 \_ 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" ``` diff --git a/docs/index.md b/docs/index.md index 1018175..46a8dbd 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 can 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..e394b03 100644 --- a/docs/learning_git.md +++ b/docs/learning_git.md @@ -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..243dfa6 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -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 _\-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 @@ -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 _\_ 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 __ with your slac unix account-name) ``` ssh -Yt @s3dflogin.slac.stanford.edu //now enter your info to login to s3df... diff --git a/docs/workflow.md b/docs/workflow.md index e8392bd..afcf56a 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