DOC: more updates to doc formating

README.md

@@ -39,7 +39,6 @@ If everything is working, the script should start spitting terminal-output like:
 3260 True
 Event number foo
 ```
-_Done with step-by-step setup. The following sections provide more detail on the setup process and the code._
 
 ## Developers:
 

docs/commands.md

@@ -1,18 +1,18 @@
 # Git Commands for Common Tasks
 
-**A)** Getting the latest changes for use at a beamtime
+### A) Getting the latest changes for use at a beamtime
 ```
 git fetch
 //if beamtime is across multiple days, use 1st day 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
 ```
 
-**C)** Saving a new feature/script/bugfix/etc:
+### C) Saving a new feature/script/bugfix/etc:
 * make sure you have the latest changes from the remote:
 ```
 git pull origin development
@@ -34,7 +34,7 @@ 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_
 
-**D)** If pulling down someone else's branch (non main/development branch):
+### D) If pulling down someone else's branch (non main/development branch):
 * get updated branch info from remote
 ```
 git fetch origin
@@ -48,7 +48,7 @@ git branch -r
 git checkout <other_person_branch_name>
 ```
 
-**E)** Switching between two branches:
+### E) Switching between two branches:
 * if the following command lists two branches:
 ```
 git branch
@@ -58,18 +58,18 @@ git branch
 git checkout <branch_want_to_switch_to>
 ```
 
-**F)** Making pull request (one branch has been pushed to the remote):
-* go to: https://github.com/slaclab/beamtime-calibration-suite/pulls  
+### F) Making pull request (one branch has been pushed to the remote):  
+* go to: [https://github.com/slaclab/beamtime-calibration-suite/pulls](https://github.com/slaclab/beamtime-calibration-suite/pulls)
 * 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 "compare: ..." box is the branch that will get merged into the "base: ..." box's branch  
   * 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 is tagged):
 
 * same syntax as checking-out a branch, but use tag name instead:
 ```

docs/environment.md

@@ -5,11 +5,11 @@ When running on S3DF, you will first need to setup your environment so you can r
 source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh
 ```
 
-Then you can execute the following to setup some project-specific things:
+Then you can execute the following to setup some project-specific things (must be ran from _beamtime-calibration-suite_ folder):
 ```
 source setup.sh
 ```
-_(This must be ran in each new terminal session, or added to your ~/.bashrc file using the full path to 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
 

docs/index.md

@@ -14,8 +14,9 @@ from calibrationSuite.basicSuiteScript import *
 from calibrationSuite.fitFunctions import * 
 from calibrationSuite.Stats import * 
 from calibrationSuite.cluster import *
+...
 ```
-_(documentation on the library functionality is still to come, but example usage is seen in the /suite_scripts folder)_
+_(documentation on the library functionality is still to come, but example usage is seen by scripts in the /suite_scripts folder)_
 
 * _/suite_scripts_: scripts that use the calibrationSuite library code ('high-level scripts')
 * _/standalone_scripts_: scripts that do not use the calibrationSuite library code ('high-level scripts')
@@ -25,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 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.

docs/learning_git.md

@@ -6,11 +6,11 @@ if you want a good understanding of git, suggest to read the first 3 chapters of
   * 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  
 
-a short presentation that summaries the book's content can be found [here](https://courses.cs.washington.edu/courses/cse403/13au/lectures/git.ppt.pdf)   
+short presentation that summaries the book's content can be found [here](https://courses.cs.washington.edu/courses/cse403/13au/lectures/git.ppt.pdf)   
 
-a 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 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)  
 
-a 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 [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)  
 

docs/workflow.md

@@ -1,12 +1,12 @@
 # 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_  
+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  
+* 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  
+* after beamtimes, we merge _beamtime_\<month>_\<day>_\<year>_ back into _main_ and tag it  
 
 (img: https://www.pablogonzalez.io/salesforce-git-branching-strategies/)