From 181cbaf7d7b30f4c2c6861a43be538aac8fae317 Mon Sep 17 00:00:00 2001 From: nstelter-slac Date: Thu, 21 Mar 2024 12:44:43 -0700 Subject: [PATCH] DOCS: Expand github-pages docs --- docs/index.md | 28 ++++++++- docs/logging.md | 27 ++++++++ docs/running.md | 15 +++++ docs/setup.md | 163 ++++++++++++++++-------------------------------- mkdocs.yml | 2 + 5 files changed, 125 insertions(+), 110 deletions(-) create mode 100644 docs/logging.md create mode 100644 docs/running.md diff --git a/docs/index.md b/docs/index.md index 5223286..ea36574 100644 --- a/docs/index.md +++ b/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 \ No newline at end of file diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 0000000..cf90be1 --- /dev/null +++ b/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 .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))) \ No newline at end of file diff --git a/docs/running.md b/docs/running.md new file mode 100644 index 0000000..69f62b9 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index bb7711c..3814410 100644 --- a/docs/setup.md +++ b/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_ 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’ 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 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 \ with your slac unix account-name) + ```     ssh -Yt @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 - -    git config --global user.email - -    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 git@github.com: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 +git config --global user.email +#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 git@github.com: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 +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c95de3a..594009a 100644 --- a/mkdocs.yml +++ b/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'