diff --git a/docs/source/_static/bluesky-ophyd-sirepo.png b/docs/source/_static/bluesky-ophyd-sirepo.png new file mode 100644 index 00000000..e44d53d0 Binary files /dev/null and b/docs/source/_static/bluesky-ophyd-sirepo.png differ diff --git a/docs/source/_static/sirepo-json-ophyd.png b/docs/source/_static/sirepo-json-ophyd.png new file mode 100644 index 00000000..6af73c86 Binary files /dev/null and b/docs/source/_static/sirepo-json-ophyd.png differ diff --git a/docs/source/_static/sirepo-ophyd-watchpoint.png b/docs/source/_static/sirepo-ophyd-watchpoint.png new file mode 100644 index 00000000..9c1aaca7 Binary files /dev/null and b/docs/source/_static/sirepo-ophyd-watchpoint.png differ diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 5b1f236b..0a0073fd 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,3 +1,6 @@ +.. _examples: + +======== Examples ======== diff --git a/docs/source/index.rst b/docs/source/index.rst index fd6bf1a3..604058b6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,13 +3,25 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -sirepo-bluesky Documentation +============================ +Sirepo-Bluesky Documentation ============================ .. toctree:: :maxdepth: 2 + overview installation examples simulations release-history + +.. toctree:: + :hidden: + :caption: Links + + Sirepo-Bluesky on GitHub + Bluesky Project + Sirepo on GitHub + Public Sirepo Server + Beamline Optimization Tools diff --git a/docs/source/installation.rst b/docs/source/installation.rst index c1a64603..255f8545 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,3 +1,5 @@ +.. _installation: + ========================= Installation instructions ========================= diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 00000000..e7ce02a7 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,52 @@ +.. _overview: + +======== +Overview +======== + +The Sirepo-Bluesky project interfaces two frameworks --- **Sirepo** and +**Bluesky**. + +`Sirepo`_ is a framework providing convenient access to various physics +simulation codes (such as `SRW`_, `Shadow3`_, etc.) via an intuitive +browser-based interface. + +`Bluesky`_ is a data collection and experiment orchestration framework +routinely used at NSLS-II and other synchrotrons for data collection & data +access, and integrates well with the scientific Python ecosystem. Core Bluesky +components include the `bluesky library`_ for experiment orchestration, the +`ophyd library`_ for device abstractions, and the `databroker library`_ for +convenient access to the experiment data. Relationships of the libraries are +shown at the `Bluesky Project`_ website. + +Combining the two systems together enables researchers to perform virtual +experiments using Sirepo as a "digital twin" of a real beamline or an +instrument. + +The scheme below shows how the libraries from the Bluesky stack communicate +with other external systems (hardware and software): + +.. image:: _static/bluesky-ophyd-sirepo.png + +The following scheme explains how an optical element in the Sirepo JSON model +turns into an Ophyd ``Device``: + +.. image:: _static/sirepo-json-ophyd.png + +The Watchpoint optical element acts as a virtual detector and the scheme below +demonstrates the code for the corresponding Ophyd class with the ``trigger`` +method and the relevant actions in the Sirepo frontent UI: + +.. image:: _static/sirepo-ophyd-watchpoint.png + +Please check the :ref:`installation` and the :ref:`examples` sections for more +details on how to get started using Sirepo-Bluesky. + +.. _Sirepo: https://www.sirepo.com +.. _Bluesky: https://blueskyproject.io +.. _SRW: https://github.com/ochubar/SRW +.. _Shadow3: https://github.com/oasys-kit/shadow3 +.. _bluesky library: https://blueskyproject.io/bluesky +.. _ophyd library: https://blueskyproject.io/ophyd +.. _databroker library: https://blueskyproject.io/databroker +.. _Bluesky Project: https://blueskyproject.io diff --git a/docs/source/release-history.rst b/docs/source/release-history.rst index 2bda6a4f..8e84e022 100644 --- a/docs/source/release-history.rst +++ b/docs/source/release-history.rst @@ -2,6 +2,18 @@ Release History =============== +v0.7.2 (2023-08-19) +------------------- + +This is a maintenance release with some documentation updates. + +Documentation +............. + +- An Overview section was added to the docs. +- External links were added to the sidebar. + + v0.7.1 (2023-08-18) -------------------