Merge pull request #143 from mrakitin/doc-update-intro

DOC: add project overview and links to relevant projects in a sidebar
NSLS-II · Aug 19, 2023 · 8378488 · 8378488
2 parents 4244521 + eea7908
commit 8378488
Show file tree

Hide file tree

Showing 8 changed files with 82 additions and 1 deletion.
diff --git a/docs/source/_static/bluesky-ophyd-sirepo.png b/docs/source/_static/bluesky-ophyd-sirepo.png
diff --git a/docs/source/_static/sirepo-json-ophyd.png b/docs/source/_static/sirepo-json-ophyd.png
diff --git a/docs/source/_static/sirepo-ophyd-watchpoint.png b/docs/source/_static/sirepo-ophyd-watchpoint.png
diff --git 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
@@ -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 <https://github.com/NSLS-II/sirepo-bluesky>
+   Bluesky Project <https://blueskyproject.io>
+   Sirepo on GitHub <https://github.com/radiasoft/sirepo>
+   Public Sirepo Server <https://www.sirepo.com>
+   Beamline Optimization Tools <https://github.com/NSLS-II/bloptools>
diff --git 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
@@ -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
@@ -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)
 -------------------