DOCS: Expand github-pages docs

docs/index.md

@@ -1,2 +1,26 @@
-# Test
-This is a test for the calibration-suite docs site!
+File organization:
+
+    /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 * 
+	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)
+
+    /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')
+
+    /tests: tests files, can be ran with 'pytest .' from the root project directory (Currently only test for the fitFunctions library file is running, more tests are to be added)
+
+    /data: example data-files used for running the scripts
+
+Current Status:
+
+main branch tag v1.0.0 are the scripts used for the 2/17/24 beamtime
+
+    only changes made are to file organization, and to import statements so work with new organization
+    large changes will be merged into ontop of this, but original scripts can be accessed by checking out this tag
+    future beamtimes can be tagged as well

docs/logging.md

@@ -0,0 +1,27 @@
+Logging
+
+Logging calls are added to the library code, and also to the EventScanParallelSlice.py and AnalyzeH5.py files in /suite_scripts to act as examples of generating logs from both the library and high-level scripts.
+
+Using the following method will append log messages to the log-file if it already exists, or create a new log-file if the file doesn't exist. If you want a new log-file for each run of a high-level script, atm you will need to rename the log-file after each run so a new one will be generated.
+
+To have your high-level script generate logs from the calibrationSuite library code, add the following at the top of the script:
+
+import os
+import calibrationSuite.loggingSetup as ls
+currFileName = os.path.basename(__file__)
+ls.setupScriptLogging(currFileName[:-3] + ".log", logging.INFO)
+
+You can pass a chosen log-file name to the setupScriptLogging function, but using the above will create and write to file named <curr script name>.log
+
+To add additional logging from the high-level script itself(to the same file specified to setupScriptLogging), you can also add the following to the top of the script:
+
+import logging
+logger = logging.getLogger(__name__)
+
+Then can add log statements throughout the script with:
+
+logger.error("Example error msg!") # for logging when the program goes wrong
+logger.exception("Example exception msg!) # for logging error and also including stack-trace in log 
+logger.info("Example info msg!") # for logging useful info on the state of the program
+
+(Note: these must take a statement evaluating to a single string, if a,b,c are strings can't do 'logger.info(a,b,c)' but can do 'logger.info(a+b+c)'. Also for example if a is an int, must do 'logger.info(str(a)))

docs/running.md

@@ -0,0 +1,15 @@
+In order to run the library code, first execute the following cmd:
+
+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 script just 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.
+
+Additionally you can specify which config file to use by setting the 'SUITE_CONFIG' environment variable, for example:
+
+export SUITE_CONFIG="rixSuiteConfig.py" 
+
+(relative or full paths work)
+You can also set the config-file using the '-cf' or '--configFile' cmd-line arguments (note: if set, the environment variable overrides this cmd-line option)
+If neither of the above are set, the suite will try to use suiteConfig.py. If no config file can be found and read, the library will fail-out early.

docs/setup.md

@@ -1,119 +1,66 @@
-Beamtime calibration suite git/github setup
+# Github and Git Setup
 
-1) Make a github.com account
+These steps will get you setup for running and developing the calibration suite
 
+## 1: Make a github.com account
 
--if already have github account and want to use it, skip to 2)
+* if you already have github account and want to use it, skip to step **2)**
+* else to make a new account follow the steps here: https://github.com/join
+* your username can be anything, some people at slac use _\<slac_username\>-slac_ convention (ex: _nstelter-slac_)
+* for email you can use ‘@slac.stanford.edu’ address or any other address if you want (just make sure to use the same email in step **4)**
+* you will need a code from your email for verification when creating the account
 
--else, follow the steps here: https://github.com/join
+## 2: Register github account with ‘SLAC Lab’ github group
 
+* first join ‘#comp-general’ channel on Slack
+* when viewing this Slack channel, should see ‘Pinned’ and next to it ‘Workflows’ at top of the page
+* click ‘Workflows’ -> ‘SLAC GitHub Access’, and fill out the form with your info
+* wait to receive an email asking you to join the ‘SLAC Lab’ group, and follow instructions in this email
 
--username can be anything, some people use ‘<slac_username>-slac’ convention (ex: nstelter-slac)
+## 3: Request write permissions for the repository
 
+*  after completing step **2)**, your github account should be a member of the 'SLAC Lab' github group
+*  now go to 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)
 
-- for email can use ‘@slac.stanford.edu’ address, or any other address if you want (just make sure to use the same email in step 3))
-
-
--will need a code from email to verify during creating account
-
-
-
-
-2) Register github account with ‘SLAC Lab’ github group
-
--join ‘#comp-general’ channel on Slack
-
--when viewing this Slack channel, should see ‘Pinned’ and next to it ‘Workflows’ at top of the page
--click ‘Workflows’ -> ‘SLAC GitHub Access’, and fill out the form with your info
-
--should receive an email later asking you to join the ‘SLAC Lab’ group, then follow the further instructions in this email
-
-
-
-
-
-
-
-For steps 3), 4), 5), 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 linux-username)
+### Note:
 
+* For the following steps **4)**, **5)**, **6)**: 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
-
     source /sdf/group/lcls/ds/ana/sw/conda2/manage/bin/psconda.sh
-
-3) Config local git settings
-
--Enter the following terminal commands:
-
-    git config --global user.name <github username>
-
-    git config --global user.email <email used to setup github account>
-
-    git config --global core.editor vim
-
--Can use editor of your choice (ex: emacs) instead of “vim”, this will be editor used to edit commit messages and some other git options
-
-
-
-
-4) Setup SSH Keys for github on s3df
-
--Make sure you are logged into github account in browser
-
--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 (make sure you have selected the 'Linux' tab near the top of the page, not 'Mac')
-
--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 (make sure you have selected the 'Linux' tab near the top of the page, not 'Mac')
-
-
-
-
-5) Download repo
-
--cd to where you want the scripts to live (the scripts will be downloaded inside of a folder called ‘beamtime-calibration-suite’)
-
-    -I suggest inside your home directory (‘~’), or inside a new folder you make like ‘~/repos/’
-
--to download the scripts, run the following command: git clone [email protected]:slaclab/beamtime-calibration-suite.git
-
-     -if an error occurs, SSH setup in step 3) may have an issue and needs to be debugged
-
--if clone is successful, you should be able to cd into newly created ‘beamtime-calibration-suite’ folder and see subfolders containing python code
-
-
--now get the 'development' branch by running command: git checkout development
-
-(For reference:
-
-   -the main scripts repo lives here: https://github.com/slaclab/beamtime-calibration-suite
-
-
-   -and to see most up-to-date code in development look at the 'development' branch: https://github.com/slaclab/beamtime-calibration-suite/tree/development)
-
-
-
-
-6) Learn Git
-
--Suggest reading first 3 chapters of https://git-scm.com/book/en/v2 :
-
-     -The following sections can be skipped if you want (more detail than needed atm),
-
-
-         -1.5, 1.6, 2.6, 2.7, 3.5, 3.6
-
-     -recommended resource by git community, gives good base-understanding of git
-
-     -but many similar tutorials exist, so feel free to use other 'intro to git/github' videos/websites if you like them better
-
--(Optional) Here is also short presentation that summaries book content: https://courses.cs.washington.edu/courses/cse403/13au/lectures/git.ppt.pdf
-
-
--(Optional) Git commands cheat sheet: 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) The following explains GitHub 'Pull Requests' feature:
-
-    -https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
-
-
-    -https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+    ```
+
+## 4: Config local git settings
+
+* Enter the following terminal commands:
+``` 
+git config --global user.name <github username>
+git config --global user.email <email used to setup github account>
+#run one of the following cmds, depending on your preferred editor 
+#(editor is used for editing files during some git operations)
+git config --global core.editor vim
+git config --global core.editor emacs
+```
+
+## 4: Setup SSH Keys for github on s3df
+
+* First make sure you are logged into github account in browser
+* 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 _(make sure you have selected the 'Linux' tab near the top of the page, not 'Mac')_
+* 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 _(make sure you have selected the 'Linux' tab near the top of the page, not 'Mac')_
+
+## 5: Download repo
+
+* cd to where you want the scripts to live (the scripts will be downloaded inside of a folder called ‘beamtime-calibration-suite’)
+  * I suggest inside your home directory (_\~_), or inside a new folder you make like _~/repos/_
+* to download the repository, run the following command: 
+```
+git clone [email protected]:slaclab/beamtime-calibration-suite.git
+```
+  * if an error occurs, SSH setup in step **3)** may have had an issue and needs to be debugged
+* if command was successful, you should be able to cd into newly created ‘beamtime-calibration-suite’ folder and see subfolders containing python code
+* now get the 'development' branch by running command (this will you get the most up-to-date code when it's not during a beamtime): 
+```
+git checkout development
+```

mkdocs.yml

@@ -4,6 +4,8 @@ repo_url: https://github.com/slaclab/beamtime-calibration-suite
 nav:
   - Home: index.md
   - Setup: setup.md
+  - Running: running.md
+  - Logging: logging.md
 
 theme:
   name: 'readthedocs'