Auto-update from Github Actions Workflow

Deployed from commit 1185e27 (refs/tags/v1.21.0)
pcdshub · Aug 26, 2024 · 9627ab1 · 9627ab1
1 parent 84dc0c9
commit 9627ab1
Show file tree

Hide file tree

Showing 181 changed files with 29,965 additions and 3 deletions.
diff --git a/index.html b/index.html
@@ -1,9 +1,9 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <meta http-equiv="Refresh" content="0; url=v1.20.0" />
+    <meta http-equiv="Refresh" content="0; url=v1.21.0" />
   </head>
   <body>
-    <p>Go to the <a href="v1.20.0">default documentation</a>.</p>
+    <p>Go to the <a href="v1.21.0">default documentation</a>.</p>
   </body>
 </html>
diff --git a/v1.21.0/.buildinfo b/v1.21.0/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 3250a0f2c57593ca6efee5129682b6aa
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/v1.21.0/_sources/beamline.rst.txt b/v1.21.0/_sources/beamline.rst.txt
@@ -0,0 +1,27 @@
+Beamline File
+=============
+
+Each hutch repository has an ``xxx/beamline.py`` file that is pointed to in
+the ``conf.yml`` file. This is intended to be a place for hutches to create
+hutch-specific objects or startup changes and additions. You are encouraged
+to port your hutch-specific classes upstream and add the objects to the
+database, but this is not necessary in every case.
+
+The import rules for this file can be thought of as the most basic:
+
+.. code-block:: python
+
+   from xxx.beamline import *
+
+
+This means we'll include everything in the module, unless an ``__all__`` list is
+found to specify the behavior of a ``*`` import.
+
+As specified on the `yaml_files` page, ``conf.yml`` can be extended to import
+from multiple modules:
+
+.. code-block:: YAML
+
+   load:
+     - xxx.beamline
+     - xxx.my_module
diff --git a/v1.21.0/_sources/bug.rst.txt b/v1.21.0/_sources/bug.rst.txt
@@ -0,0 +1,13 @@
+bug.py
+======
+.. automodule:: hutch_python.bug
+
+    .. autosummary::
+       :toctree: generated
+       :nosignatures:
+
+       hutch_python.bug.get_current_environment
+       hutch_python.bug.get_last_n_commands
+       hutch_python.bug.get_text_from_editor
+       hutch_python.bug.report_bug
+       hutch_python.bug.post_to_github
diff --git a/v1.21.0/_sources/cache.rst.txt b/v1.21.0/_sources/cache.rst.txt
@@ -0,0 +1,8 @@
+cache.py
+========
+
+.. automodule:: hutch_python.cache
+
+   .. autoclass:: LoadCache
+      :members:
+      :special-members: __call__
diff --git a/v1.21.0/_sources/cli.rst.txt b/v1.21.0/_sources/cli.rst.txt
@@ -0,0 +1,4 @@
+cli.py
+======
+
+.. automodule:: hutch_python.cli
diff --git a/v1.21.0/_sources/daq.rst.txt b/v1.21.0/_sources/daq.rst.txt
@@ -0,0 +1,90 @@
+DAQ
+===
+
+The following objects are provided for interacting with the data acquisition
+system:
+
+    - ``daq``: controls execution of the run
+    - ``scan_pvs``: controls the auxilliary scan pvs, which are used to
+      organize the run tables.
+
+Full documentation is available at `<https://pcdshub.github.io/pcdsdaq>`_.
+This page will be a brief overview.
+
+.. note::
+
+   ``scan_pvs`` are disabled by default! This is to prevent confusion from
+   two users accidentally writing to the PVs at the same time. Call
+   ``scan_pvs.enable()`` to enable them. You may consider doing this as part
+   of your standard scan routine.
+
+
+Basic Usage
+-----------
+
+Use ``daq.begin`` to start a run. Runs must be ended explicitly or the
+run will remain open. A second call to a begin during an open run will
+resume the run.
+
+.. ipython:: python
+   :suppress:
+
+   from bluesky.run_engine import RunEngine
+   from bluesky.plans import scan
+   from ophyd.sim import motor
+   from pcdsdaq.daq import Daq
+   from pcdsdaq.sim import set_sim_mode
+
+   set_sim_mode(True)
+   RE = RunEngine({})
+   daq = Daq(RE=RE)
+
+.. ipython:: python
+
+   # Run for 120 events, wait, leave the run open.
+   daq.begin(events=120, wait=True)
+   # Close the run
+   daq.end_run()
+   # Run for 1 second, record, set the run to end automatically
+   daq.begin(duration=1, record=True, end_run=True)
+   # Wait until done taking data
+   daq.wait()
+
+The python will steal control from the GUI. Only one or the other can have
+control at a time. Use ``daq.disconnect`` to give up control to the GUI.
+
+.. ipython:: python
+
+   daq.disconnect()
+
+You can start an infinite run using ``daq.begin_infinite``. You can stop this
+run manually using ``daq.end_run``.
+
+
+In a Scan
+---------
+
+Use the ``daq`` object as your detector to include it in a ``bluesky`` plan.
+The ``DAQ`` will then run for the configured duration at every scan step.
+If ``scan_pvs`` are enabled, these will be written to during the ``bluesky``
+plan.
+
+.. ipython:: python
+
+   # Configure for 120 events per point
+   daq.preconfig(events=120)
+   # Scan motor from 0 to 10 in 11 steps, run daq at each point
+   RE(scan([daq], motor, 0, 10, 11))
+
+
+Controlling Post-Scan State
+---------------------------
+
+The daq will return to the state it was in before the scan was run. If we
+start disconnected, we will revert to disconnected. If we start configured,
+we will stay connected and configured. If we start while already running,
+we'll start running again (``record=False``) after the scan.
+
+The ``daq.configure`` method must connect, so the ``daq.preconfig``
+method is provided if you'd like to schedule a configuration to apply
+upon connecting in the scan.
diff --git a/v1.21.0/_sources/database.rst.txt b/v1.21.0/_sources/database.rst.txt
@@ -0,0 +1,26 @@
+Database Objects
+================
+
+Database objects are objects that are loaded from the shared device database.
+This has the advantage of allowing us to have consistent devices across
+different hutches and it reduces clutter in the `beamline <beamline>` file.
+
+After loading a ``hutch-python`` session, a file is created at ``xxx/db.txt``
+detailing every device that was loaded, in the order they were loaded.
+This file has no function, but it serves as rough guide for understanding
+which objects the database is providing.
+
+All database objects can be found in a special module called ``xxx.db`` that
+is created at runtime. This will work like a normal module you can import
+from:
+
+.. code-block:: python
+
+    from bluesky.plans import scan
+    from mfx.db import RE, mfx_attenuator
+
+    RE(scan([], mfx_attenuator, 0, 1, 10))
+
+
+This can be used to bring database or `beamline <beamline>` objects into the
+`experiment <experiment>` file.
diff --git a/v1.21.0/_sources/debug.rst.txt b/v1.21.0/_sources/debug.rst.txt
@@ -0,0 +1,139 @@
+Debug
+=====
+
+There are numerous debug features built in to ``hutch-python``.
+
+Live Session Logging
+--------------------
+
+The first place to go when something has already gone wrong is to the log
+files. These are stored in a ``logs`` directory in the same location as the
+``conf.yml`` file, and sorted by date and session start time.
+
+These contain every log message from the session in the order they were called.
+Each module can choose when to make calls to ``logger.debug`` to generate
+log messages, but we also log every single input line, output line, and
+exception that was raised in the interactive session. Note that the input and
+output lines are not available to the logger until the entire command has
+executed, so the log messages immediately preceding an input log are those
+that were created by calling that statement.
+
+The logging configuration is specified by the ``logging.yaml`` file and is
+set up by the :py:mod:`log_setup` module. If not in debug mode, only log levels
+``INFO`` and above will make it to the terminal. The files are configured to
+rotate and roll over into a second file once they get too large.
+
+
+Default Log Filtering Rules
+---------------------------
+The following filtering rules are applied to the console logs:
+
+- Loggers and ophyd object logging adapters that send many messages in a short
+  period of time will stop being logged. This can be configured using the
+  ``logs.filter`` object.
+- Calls to ``warnings.warn`` will be redirected to the ``logging`` module
+  stream at "WARNING" level, and duplicate messages will be dropped to "DEBUG"
+  level for the console. This is similar to how warnings behave normally
+  outside of IPython sessions, but this way we also get a record of them in
+  the normal log file.
+- Subscription callback exceptions from ophyd objects will be demoted from
+  "ERROR" level to "DEBUG" level to prevent spam while preserving error
+  logs.
+- All log messages from ophyd objects at "INFO" level will also be demoted to
+  "DEBUG" level to prevent spam.
+
+
+PCDS-wide Logging
+-----------------
+
+A special Python logger for PCDS-wide logging is pre-configured within
+``hutch-python``.  This special logger is named ``'pcds-logging'``, and hooks
+in with our managed logstash, ElasticSearch and Grafana stack.
+
+To explore the data, access Grafana `here
+<https://pswww.slac.stanford.edu/ctl/grafana/explore>`_.
+
+To record information, first get the logger itself:
+
+.. code-block:: python
+
+    import logging
+    pcds_logger = logging.getLogger('pcds-logging')
+
+
+Log messages above the configured level (by default ``logging.DEBUG``) will be
+transmitted to the centralized log server to be recorded and indexed.
+
+One example use case is when an important event that would be useful to see
+trended over time:
+
+.. code-block:: python
+
+    pcds_logger.info('I dropped the sample')
+
+
+Or for exception statistics, perhaps. The following will include a full stack
+trace along with module and line information automatically:
+
+
+    try:
+        1/0
+    except ZeroDivisionError:
+        pcds_logger.exception('This specific thing went wrong')
+
+
+It is not necessary to include information about the host that is running
+Python, module versions, or thread/process names as these are automatically
+included.
+
+
+Debug Mode and Logging Tools
+----------------------------
+
+You can start in debug mode by passing the ``--debug`` option to
+``hutch-python``. Debug mode changes the logging configuration to print
+log messages of level ``DEBUG`` and above to the screen. If that's a bit much,
+or if you change your mind during a session, we have a ``logs`` namespace
+with all of the relevant logging configuration tooling.
+
+- `logs.log_objects <hutch_python.log_setup.log_objects>`
+        Used to configure ``DEBUG`` level logging for specific devices.
+- `logs.log_objects_off <hutch_python.log_setup.log_objects_off>`
+        Used to reset previous calls to ``log_objects``.
+- `logs.get_log_directory <hutch_python.log_setup.get_log_directory>`
+        Returns the current configured log path.
+- `logs.get_session_logfiles <hutch_python.log_setup.get_session_logfiles>`
+        Returns a list of all the logfiles generated by this session.
+- `logs.get_console_level_name <hutch_python.log_setup.get_console_level_name>`
+        Returns the name of the console's log level, e.g. "INFO"
+- `logs.set_console_level <hutch_python.log_setup.set_console_level>`
+        Change the log level of the console logging handler.
+- `logs.debug_mode <hutch_python.log_setup.debug_mode>`:
+        A shortcut for setting the console level between "INFO" and "DEBUG".
+- `logs.debug_context <hutch_python.log_setup.debug_context>`:
+        Context manager for enabling debug mode for a block of code.
+- `logs.filter <hutch_python.log_setup.ObjectFilter>`:
+        Get the ophyd object filter that's on the console handler.
+        This contains a whitelist for allowing spammy loggers and a blacklist
+        for hiding non-spammy loggers.
+- `logs.file_filter <hutch_python.log_setup.ObjectFilter>`:
+        The same as above, but for the file handler.
+
+
+.. code-block:: python
+
+   logs.debug_mode(True)     # Turn on debug mode
+   logs.debug_mode(False)    # Turn off debug mode
+   print(logs.debug_mode())  # Check debug mode
+
+   # Turn on debug mode for the duration of a code block
+   with logs.debug_context():
+       buggy_function(arg)
+
+
+Automated Test Logging
+----------------------
+
+If you're running the automated test suite, each test run is stored in a
+module-level ``logs`` folder. This can be useful for diagnosing why the tests
+are failing.
diff --git a/v1.21.0/_sources/environment.rst.txt b/v1.21.0/_sources/environment.rst.txt
@@ -0,0 +1,33 @@
+Environments
+============
+
+Central Install
+---------------
+
+Each hutch repository is hard-coded to use the central ``conda`` installs.
+You can change this in your developer checkout by editing the ``xxxversion``
+file. Take care not to commit changes to this file except to update the central
+install version.
+
+For ``python=3.6``, the central install is at ``/reg/g/pcds/pyps/conda/py36``.
+It is managed using the `pcds-envs <https://github.com/pcdshub/pcds-envs>`_
+module.
+
+You can activate the base environment by calling
+``source /reg/g/pcds/pyps/conda/py36env.sh``.
+This will give you the latest, you can pick an older environment with
+``source /reg/g/pcds/pyps/conda/py36env.sh $ENVNAME``. If you take latest and
+run ``conda env list``, you'll see all of the options.
+
+Personal Install
+----------------
+
+You may wish to install ``hutch-python`` into your own environment for
+development purposes. This can be achieved trivially if your environment is in
+`conda <https://conda.io/docs>`_. If your environment is not in conda, I
+highly suggest downloading `miniconda <https://conda.io/miniconda.html>`_
+and giving it a try.
+
+To pick up all dependencies, run this command:
+
+``conda install hutch-python -c pcds-tag -c defaults -c conda-forge``