installation steps need some updates

[prjemian]

Just installing new instrument for HEXM and identified some matters for update.

1. Under Setup a bluesky instrument:

/APSshare/bin/new_bluesky_instrument.py would not run.

• Tried python /APSshare/bin/new_bluesky_instrument.py but user account had Python2.7 as default.
• Tried python3 /APSshare/bin/new_bluesky_instrument.py but requests package was not installed.
• Tried /APSshare/miniconda/x86_64/bin/python /APSshare/bin/new_bluesky_instrument.py but the workstation could not reach web sites outside the firewall.
• Finished the installation from a workstation with outside access.

2. Create the conda environment

   • Also need to run from a workstation with outside access.

3. This is a good point to Start version control

• create the GitHub organization (if the group does not already have one)
• create the GitHub repo
• clone the repo locally
• copy the .git/ folder from the clone into ~/bluesky/ (this makes ~/bluesky/ a repo)
• git add and git commit the existing content in the new bluesky directory (before any configuration changes are made)
• Need to get a .gitignore file (new_bluesky_instrument.py script should do this)

5. Activate the conda environment

   • no conda command, need to get that first: source /APSshare/miniconda/x86_64/bin/activate

6. Test the new bluesky instrument

• Must create the IPython profile before this step.
• Should Setup your databroker catalog configuration before this step
• Needed to edit the blueskyStarter.sh file.
  • Specific changes in the new repo: https://github.com/APS-1ID-MPE/hexm-bluesky/commit/f71495c9fa68e48b43e6b2431bc64763b2c270ca
  • must be executable: chmod +x blueskyStarter.sh

With these changes, the instrument package started.

[prjemian]

I think this issue is for me. @rodolakis, if you run into any of these problems, or others, add them here.

[prjemian]

In [6]: %run -i user/quick_hello.py
Loading 'Hello, World!' example.

In [7]: listplans()
Out[7]: 
======================= ==================================================
plan                    doc                                               
======================= ==================================================
redefine_motor_position Set EPICS motor record's user coordinate to `` ...
hello_world             Simple bluesky plan for demonstrating Hello, W ...
======================= ==================================================

In [8]: RE(hello_world())

Transient Scan ID: 1     Time: 2023-04-27 17:36:26
Persistent Unique Scan ID: '98bb9fc8-e9d6-4a2e-985e-eef7756ca0ca'
New stream: 'primary'
+-----------+------------+------------+
|   seq_num |       time |      hello |
+-----------+------------+------------+
|         1 | 17:36:27.0 |          1 |
+-----------+------------+------------+
generator count ['98bb9fc8'] (scan num: 1)
Out[8]: ('98bb9fc8-e9d6-4a2e-985e-eef7756ca0ca',)

In [9]: listruns()
/home/beams/BDP/.conda/envs/bluesky_2023_2/lib/python3.10/site-packages/databroker/queries.py:89: PytzUsageWarning: The zone attribute is specific to pytz's interface; please migrate to a new time zone provider. For more details on how to do so, see https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html
  timezone = lz.zone
Out[9]: 
======= =================== ========= =========
scan_id time                plan_name detectors
======= =================== ========= =========
1       2023-04-27 17:36:26 count     ['hello']
======= =================== ========= =========

In [10]: listobjects()
Out[10]: 
============ =========== ============== ========
name         class       PV (or prefix) label(s)
============ =========== ============== ========
hello_device HelloDevice                        
============ =========== ============== ========

In [11]: 

[rodolakis]

@prjemian I have already addressed (or in the process of addressing) 1,2 and 5 in my 112-installation branch. I have no problem taking care of 3. 6 is to be addressed with issue #104. I leave to you to fix the blueskyStarter.sh (there is no 4!)

[prjemian]

Palm-to-forehead-moment now for me. Thanks!

[rodolakis]

I have been differentiating both cases: access to APSshare vs no access to APSshare

[rodolakis]

same goes to activate conda for example (source APSshare or not). Which makes me wonder, should we just have to version of the installation?

[prjemian]

You suggesting two sets of instructions? One for APS, other for non-APS? Might be easier to read. We just have to keep both in sync.

[rodolakis]

Yes, I think it would improve the readability.

[prjemian]

Or, we could use a tabbed section for these two descriptions. See this part of the NeXus manual: https://manual.nexusformat.org/examples/python/simple_example_basic/index.html#read-a-nexus-hdf5-file which shows instructions for two different ways.

[prjemian]

Needs additional configuration: https://github.com/nexusformat/definitions/blob/e9f7406b252a4b209bb50da830e2d27c7f280c9c/manual/source/conf.py#L50

then blocks such as this:

    .. tabs::

        .. tab:: APS

            ReStructured text instructions for APS users

        .. tab:: General

            ReStructured text instructions for workstations not at the APS subnet.

[prjemian]

And the environment needs another package: https://github.com/nexusformat/definitions/blob/e9f7406b252a4b209bb50da830e2d27c7f280c9c/requirements.txt#L7

[rodolakis]

I would not call it "APS users", that has a different meaning for a lot of us.

[prjemian]

I've got a couple more changes in my branch to commit.

[prjemian]

Checked my local branch: git grep -i "aps user" and it found nothing. Good, avoiding that encoded phrase.

[prjemian]

My branch is ready for your review: https://github.com/BCDA-APS/bluesky_training/pull/128

I switched the document from markdown to rst:

pandoc --from markdown --to rst _install_new_instrument.md | tee _install_new_instrument.rst

Of course this meant some hand-editing.

But notice how the details dropdowns align nicely now. And the tabbed instructions to activate conda do not look chaotic now.

Also had to update a couple cross-references from other markdown documents.

[prjemian]

Just published this new version: https://bcda-aps.github.io/bluesky_training/instrument/_install_new_instrument.html

[prjemian]

One more change applied.

[prjemian]

All changes marked for issue #112.

[prjemian]

Also need: chmod +x ~/bluesky/qserver.py ~/bluesky/qstarter.sh ~/bluesky/run_qstarter_py.sh

[rodolakis]

Create separate issues for:

• 3. This is a good point to Start version control => issue #141
• 5. Needed to edit the blueskyStarter.sh => issue #142