Instructions to install new instrument from template

[prjemian]

• close #41
• close #78

[prjemian]

This is work-in-progress, so marked as draft for now.

[prjemian]

Will request review from @mdwyman and @rodolakis when ready.

[coveralls]

Pull Request Test Coverage Report for Build 4452669673

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 1 unchanged line in 1 file lost coverage.
• Overall coverage decreased (-0.09%) to 80.114%

---

Files with Coverage Reduction	New Missed Lines	%
bluesky/instrument/devices/temperature_signal.py	1	93.22%
<!--	Total:	1		-->

Totals
Change from base Build 4393688777:	-0.09%
Covered Lines:	846
Relevant Lines:	1056

---

💛 - Coveralls

[prjemian]

Lots of detail. Needs a 10,000 foot overview for the very impatient. Move deeper explanations to separate files?

[prjemian]

@mdwyman @rodolakis @keenanlang This is ready for review

[prjemian]

The most important part of this PR is the new guide to install a bluesky instrument package from the template in this repository. See that new document here.

I plan to transition everything from the https://github.com/BCDA-APS/use_bluesky repo, per issue #76. In a future PR.

[prjemian]

@canismarko @tguruswamy Could you take a look at the (new) installation instructions in this PR? Comments welcome!

[prjemian]

[Tuesday 6:25 PM] Henke, Steven

The instructions read well. A few thoughts:

1. I noticed that the link to blueskyStarter.sh is broken. Maybe that's fixed after the merge?
2. Fewer options for the conda environment variable name might avoid strange edge cases, especially if the values get out of sync.
3. There may not be an issue, but it's worth confirming that these instructions work for csh users. This often causes troubles with DM because none of the developers use csh, but some users do.

[prjemian]

Reviewing with Joe Sullivan, discovered another problem when running new_bluesky_instrument.py with the system Python on RHEL8 (Py3.6), failures due to the use of f-strings. Need to make a note about such problems and use bash shell with source /APSshare/miniconda/x86_64/bin/activate to get a minimum Python version (with requests package). The suggestion, then:

bash
source /APSshare/miniconda/x86_64/bin/activate
python /APSshare/bin/new_bluesky_instrument.py /tmp/bluesky  # for a demo

[tguruswamy]

I ran into an issue with the new_bluesky_instrument.py script:

$ /APSshare/anaconda3/x86_64/bin/python3 /APSshare/bin/new_bluesky_instrument.py bluesky
INFO:__main__:Installing to: 'bluesky'
INFO:__main__:Downloading 'https://github.com/BCDA-APS/bluesky_training/archive/refs/heads/main.zip'
INFO:__main__:Extracting content from '/tmp/bluesky_training-main.zip'
INFO:__main__:Installing to 'bluesky'
Traceback (most recent call last):
  File "/APSshare/bin/new_bluesky_instrument.py", line 272, in <module>
    new_instrument_from_template(destination)
  File "/APSshare/bin/new_bluesky_instrument.py", line 95, in new_instrument_from_template
    move_content(destination / HEADER, destination)
  File "/APSshare/bin/new_bluesky_instrument.py", line 144, in move_content
    shutil.copy2(item, destination / target)
  File "/APSshare/anaconda3/x86_64/lib/python3.9/shutil.py", line 443, in copy2
    copyfile(src, dst, follow_symlinks=follow_symlinks)
  File "/APSshare/anaconda3/x86_64/lib/python3.9/shutil.py", line 265, in copyfile
    with open(src, 'rb') as fsrc, open(dst, 'wb') as fdst:
FileNotFoundError: [Errno 2] No such file or directory: 'bluesky/bluesky/README.md'

and indeed, there is an extra folder level in the heirarchy:

$ realpath README.md 
/home/beams2/TGURUSWAMY/src/bluesky/bluesky_training-main/bluesky/README.md

[tguruswamy]

Reviewing with Joe Sullivan, discovered another problem when running new_bluesky_instrument.py with the system Python on RHEL8 (Py3.6), failures due to the use of f-strings. Need to make a note about such problems and use bash shell with source /APSshare/miniconda/x86_64/bin/activate to get a minimum Python version (with requests package). The suggestion, then:

bash
source /APSshare/miniconda/x86_64/bin/activate
python /APSshare/bin/new_bluesky_instrument.py /tmp/bluesky  # for a demo

You can also directly run the script with the /APSshare python, which effectively runs it in that environment (it sets $PYTHONPATH / sys.path but not $PATH):

/APSshare/anaconda3/x86_64/bin/python3 /APSshare/bin/new_bluesky_instrument.py bluesky

[prjemian]

Show command to identify the Python version: python --version

[prjemian]

emphasize how to activate conda base environment

[prjemian]

I ran into an issue with the new_bluesky_instrument.py script:

repaired in 80778bf

[prjemian]

• I noticed that the link to blueskyStarter.sh is broken. Maybe that's fixed after the merge?

repaired in 4d5e5b9

[prjemian]

Re: remove extra environment variables, the problem is shown here:

bluesky/blueskyStarter.sh:# either: BLUESKY_ENVIRONMENT or BLUESKY_ENV or BLUESKY_CONDA_ENV or DEFAULT_ENV
bluesky/blueskyStarter.sh:export ENV_NAME="${BLUESKY_ENVIRONMENT:-${BLUESKY_ENV:-${BLUESKY_CONDA_ENV:-${DEFAULT_ENV}}}}"

Here are the uses to address:

bluesky/environments/admin/bluesky.md:export BLUESKY_CONDA_ENV=bluesky_2023_2
bluesky/environments/admin/bluesky.md:export BLUESKY_ENV=bluesky_2023_2
bluesky/environments/admin/bluesky.md:export BLUESKY_ENVIRONMENT=bluesky_2023_2

bluesky/environments/environment_2023_1.yml:# export BLUESKY_CONDA_ENV=bluesky_2023_1

resources/install_new_instrument.md:export BLUESKY_CONDA_ENV=bluesky_2023_2
resources/install_new_instrument.md:export BLUESKY_ENV=bluesky_2023_2
resources/install_new_instrument.md:export BLUESKY_ENVIRONMENT=bluesky_2023_2

Ok, settle on only using BLUESKY_CONDA_ENV