docs: improved documentation; added how tos; added glossary

docs/source/autodoc/autodoc.rst

@@ -1,22 +0,0 @@
-Source code
------------
-
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-module-template.rst
-   :recursive:
-
-   scan_bundler
-   scan_server
-   bec_client
-   file_writer
-   bec_utils
-   device_server
-
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/source/conf.py

@@ -9,7 +9,6 @@ import datetime
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
 import pathlib
-import sys
 
 project = "BEC"
 copyright = f"{datetime.datetime.today().year}, Paul Scherrer Institute, Switzerland"
@@ -31,26 +30,19 @@ def get_version():
 release = get_version()
 
 
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../scan_bundler")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../scan_server")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../bec_client")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../bec_utils")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../file_writer")))
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../device_server")))
-
 extensions = [
-    "sphinx.ext.autodoc",  # Core library for html generation from docstrings
-    "sphinx.ext.autosummary",  # Create neat summary tables
-    "sphinx.ext.todo",
-    "recommonmark",
-    "sphinx_copybutton",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    # "sphinx.ext.coverage",
+    # "sphinx.ext.napoleon",
     "sphinx_toolbox.collapse",
 ]
-autosummary_generate = False  # Turn on sphinx.ext.autosummary
-add_module_names = False  # Remove namespaces from class/method signatures
-autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
-set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
-autoclass_content = "both"
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+# add_module_names = True  # Remove namespaces from class/method signatures
+# autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
+# set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
+autoclass_content = "both"  # Include both class docstring and __init__
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -61,13 +53,10 @@ language = "Python"
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# html_theme = 'alabaster'
-html_theme = "pydata_sphinx_theme"
-html_static_path = ["_static"]
+html_theme = "sphinx_rtd_theme"
+# html_theme = "pydata_sphinx_theme"
+# html_static_path = ["_static"]
 # html_theme_options = {
-#     "switcher": {
-#         "json_url": "https://beamline-experiment-control.readthedocs.io/en/latest/_static/switcher.json",
-#         "version_match": "master",
-#     },
-#     "navbar_start": ["navbar-logo", "version-switcher"],
+#     "show_nav_level": 1,
+#     "navbar_align": "left",
 # }

docs/source/index.rst

@@ -14,5 +14,13 @@ Beamline Experiment Control
    usage/installation
    usage/quickstart
    usage/bec_config
+   usage/howto
+   modules
+   usage/glossary
 
 
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/requirements.txt

@@ -1,4 +1,4 @@
-sphinx == 5.3.0
+sphinx
 pydata_sphinx_theme
 sphinx_copybutton
 recommonmark

docs/source/usage/how_to/create_new_scans.rst

@@ -0,0 +1,21 @@
+How to create new scans
+-----------------------
+
+However, sometimes we want to run a sequence of functions as if it were a scan. For example, we might want to run a grid scan (2D scan) with our sample motor stages but move the sample position in z after each 2D scan. 
+Normally, this would create multiple output files that one would need to merge together later. 
+
+This is where the scan definition comes in: it allows us to run a sequence of functions as if it were a scan, resulting in a single :term:`scan_number`, a single :term:`scanID` and a single output file. 
+
+
+.. code-block:: python
+
+    @scans.scan_def
+    def overnight_scan():
+        open_shutter()
+        samx_in()
+        for i in range(10):
+            scans.grid_scan(dev.samy, 0, 10, steps=100, exp_time=1, relative=False)
+        samx_out()
+        close_shutter()
+
+By adding the decorator ``@scans.scan_def`` to the function definition, we mark this function as a scan definition.

docs/source/usage/how_to/write_a_script.rst

@@ -0,0 +1,40 @@
+How to write a script
+-----------------------
+
+Scripts are user defined functions that can be executed from the BEC console. They are stored in the ``scripts`` folder and can be edited with any text editor. 
+The scripts are loaded automatically on startup of the BEC console but can also be reloaded by typing ``bec.load_all_user_scripts()`` in the BEC console.
+An example of a user script could be a function to move a specific motor to a predefined position:
+
+.. code-block:: python 
+
+    def samx_in():
+        umv(dev.samx, 0)
+
+or 
+
+.. code-block:: python
+
+    def close_shutter():
+        print("Closing the shutter")
+        umv(dev.shutter, 0)
+
+
+A slightly more complex example could be a sequence of scans that are executed in a specific order:
+
+.. code-block:: python
+
+    def overnight_scan():
+        open_shutter()
+        samx_in()
+        for i in range(10):
+            scans.line_scan(dev.samy, 0, 10, steps=100, exp_time=1, relative=False)
+        samx_out()
+        close_shutter()
+
+This script can be executed by typing ``overnight_scan()`` in the BEC console and would execute the following sequence of commands:
+
+1. Open the shutter
+2. Move the sample in
+3. Perform 10 line scans on the sample
+4. Move the sample out
+5. Close the shutter

docs/source/usage/howto.rst

@@ -0,0 +1,8 @@
+**********
+How to ...
+**********
+
+
+.. include:: how_to/write_a_script.rst
+
+.. include:: how_to/create_new_scans.rst