Changeset 1011

Timestamp:

Jul 13, 2012 2:03:45 PM (11 years ago)

Author:

jemian

Message:

various things while discussing with Christian

Location:

specdomain/trunk/src/specdomain

Files:

• comparison/auto.mac (modified) (25 diffs)
• comparison/conf.py (modified) (1 diff)
• comparison/index.rst (modified) (1 diff)
• comparison/starter.py (modified) (1 diff)
• doc/bpm.mac (modified) (1 diff)

specdomain/trunk/src/specdomain/comparison/auto.mac

@@ -1 +1 @@
 """
-===================
-General Information
-===================
-
 Summary
 =======
@@ -136 +132 @@
 
 No special configuration is needed to run these macros. Simply load the macro
-file and run ''auto_setup''::
+file and run ``auto_setup``::
 
 > qdo auto.mac
@@ -323 +319 @@
 def auto_help '{
   """
-  Summary
-  -------
   Displays the auto help text.
 
-  Usage
-  -----
-  ::
+  Usage::
 
      > auto_help
@@ -368 +360 @@
 def auto_setup '{
   """
-  Summary
-  -------
-    Set up the control parameters for the automatic filter and exposure
-    adjustments.
-
-  Description
-  -----------
+  Set up the control parameters for the automatic filter and exposure
+  adjustments.
+
+  Description:
+
     The following parameters can be adjusted to fit the particular needs of an
     experiment or detector type (global variables holding these parameters and
@@ -462 +452 @@
       due to inconsistent choices of control parameters. [AUTO_RETRY_MAX = 20]
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_setup
@@ -507 +495 @@
 def auto_off '{
   """
-  Summary
-  -------
   Turn off any automatic filter and exposure adjustments.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_off
@@ -519 +503 @@
   .. note:: This command is equivalent to ``auto_set_level 0``
 
-  See also
-  --------
-  auto_set_level, auto_on
+  .. seealso::
+     :spec:def:`auto_set_level`,
+     :spec:def:`auto_on`
 
   """
@@ -531 +515 @@
 
 #------------------------------------------------------------------------------
-def auto_on '{auto_set_level $*}'
-
+def auto_on '{
+  """
+  See :spec:def:`auto_set_level`
+  """
+auto_set_level $*
+
+}'
+
+#------------------------------------------------------------------------------
 def auto_set_level '{
   """
-  Summary
-  -------
   Set the level of automatic filter and exposure adjustments.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_set_level [<level>]
@@ -551 +538 @@
         if <level> is ommitted, the users is asked for input
 
-  Example
-  -------
-  ::
+
+        ===== =================================================================
+        Level Description
+        ===== =================================================================
+        0     No automatic adjustments are made
+        1     Only filters are adjusted, no exposure time adjustments
+        2     Both filters and exposure times are automatically adjusted
+        ===== =================================================================
+
+
+  Examples::
 
     > auto_set_level
@@ -564 +559 @@
      ``auto_set_level`` and ``auto_on`` are equivalent to each other
 
-  See also
-  --------
-  auto_off
+  .. seealso::
+     :spec:def:`auto_off`
 
   """
@@ -713 +707 @@
 def auto_set_mode '{
   """
-  Summary
-  -------
   Set the acquisition mode to be used for the automatic filter and
   exposure time adjustments.
 
-  Description
-  -----------
-  Need some more details here...
-
-
-  Usage
-  -----
-  ::
+  Description:
+
+    Need some more details here...
+
+
+  Usage::
 
     > auto_set_mode [<mode>]
@@ -733 +723 @@
         when called with no arguments, the user is prompted
 
-  Example
-  -------
-  ::
+  Example::
 
     > auto_set_mode 1
         use the pilot exposure mode for automatic adjustments.
 
-  See also
-  --------
-  auto, auto_setup
+  .. seealso::
+
+    :spec:def:`auto_setup`
 
   """
@@ -776 +764 @@
 def auto_set_exposure '{
   """
-  Summary
-  -------
   Set the maximum and minimum exposure times used for automatic exposure
   adjustments.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_set_exposure [<min> <max>]
@@ -789 +773 @@
         when called with no arguments, the user is prompted
 
-  Example
-  -------
-  ::
-
-    > auto_set_exposure 1 10
-        sets the minimum exposure time to 1 sec and the maximum to 10 sec.
+  Arguments:
+
+  :param float min_exptime: minimum exposure time [s]
+  :param float max_exptime: maximum exposure time [s]
+
+  Example:
+
+    * set the minimum exposure time to 1 sec and the maximum to 10 sec::
+
+      > auto_set_exposure 1 10
 
   """
@@ -821 +809 @@
 def auto_show '{
   """
-  Summary
-  -------
   Display the current auto settings.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_show
@@ -871 +855 @@
 def auto_show_exposure '{
   """
-  Summary
-  -------
   Display the current auto-level exposure settings.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > auto_show_exposure
@@ -901 +881 @@
 
   .. note::
-     The option numbers must be kept in sync between ``_auto_set_option`` and
-     ``_auto_print_setup``.
+     The option numbers must be kept in sync between
+     :spec:def:`_auto_set_option` and
+     :spec:def:`_auto_print_setup`.
   """
 
@@ -938 +919 @@
 def _auto_set_option '{
   """
-  Summary
-  -------
   Sets a new value for a given option
 
-  Description
-  -----------
-  Sets a new value for a given option from the options menu that was created
-  with the _auto_print_setup command.
+  Description:
+
+    Sets a new value for a given option from the options menu that was created
+    with the :spec:def:`_auto_print_setup` command.
 
   .. note::
-     The option numbers must be kept in sync between ``_auto_set_option`` and
-     ``_auto_print_setup``.
+     The option numbers must be kept in sync between
+     :spec:def:`_auto_set_option` and
+     :spec:def:`_auto_print_setup`.
 
   """
@@ -1181 +1161 @@
 def _auto_analyze_exposure '{
   """
-  Summary
-  -------
   Analyze the previous exposure
 
-  Description
-  -----------
-  This macro retrieves the necessary information to analyze the last exposure
-  and to initiate adjustments, if necessary. Usually, this step consists only
-  of retrieving the count value from the monitored SPEC counter, but for more
-  sophisticated experimental setups, this definition could be overwritten to
-  include non-standard procedures, such as retrieving counts from EPICS PVs,
-  etc.
-
-  Usage
-  -----
-  ::
+  Description:
+
+    This macro retrieves the necessary information to analyze the last exposure
+    and to initiate adjustments, if necessary. Usually, this step consists only
+    of retrieving the count value from the monitored SPEC counter, but for more
+    sophisticated experimental setups, this definition could be overwritten to
+    include non-standard procedures, such as retrieving counts from EPICS PVs,
+    etc.
+
+  Usage::
 
     > _auto_analyze_exposure
@@ -1210 +1186 @@
 def _auto_adjust() '{
   """
-  Summary
-  -------
   Calculate and apply necessary exposure time and filter adjustments.
 
-  Description
-  -----------
-  The function returns 1 if transmission or exposure time are changed, 0
-  otherwise.
+  Description:
+
+    The function returns 1 if transmission or exposure time are changed, 0
+    otherwise.
 
   """
@@ -1431 +1405 @@
 def _auto_check_exposure '{
   """
-  Summary
-  -------
   Make sure the user-entered exposure times are consistent
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > _auto_check_exposure
@@ -1457 +1427 @@
 def _auto_check_levels '{
   """
-  Summary
-  -------
   Make sure the user-entered count levels are consistent
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > _auto_check_levels
@@ -1490 +1456 @@
 def _auto_calc_exposure(t) '{
   """
-  Summary
-  -------
   Make sure the requested exposure time is between the min and max values and
   round it to the given count time precision.
 
-  Usage
-  -----
-  ::
+  Usage::
 
     > adjusted_time = _auto_calc_exposure(requested_time)
@@ -1522 +1484 @@
 def _auto_adjust_redo() '{
   """
-  Summary
-  -------
   Determines whether the auto-adjusting has been successful.
 
-  Description
-  -----------
-  If the current exposure does not meet the required criteria, counting
-  is repeated until the best possible filter and exposure settings have been
-  obtained, or a maximum number of retry counts has been reached.
-  The function returns 1 in case of success, 0 otherwise.
-
-  Usage
-  -----
-  ::
+  Description:
+
+    If the current exposure does not meet the required criteria, counting
+    is repeated until the best possible filter and exposure settings have been
+    obtained, or a maximum number of retry counts has been reached.
+    The function returns 1 in case of success, 0 otherwise.
+
+  Usage::
 
     > success = _auto_adjust_redo()
 
   .. note::
-     This macro makes use of the ``recount`` macro, which has to be added to SPEC
-     during the startup procedure.
+     This macro makes use of the :spec:def:`recount` macro, which has to be
+     added to SPEC during the startup procedure.
 
   """
@@ -1586 +1544 @@
   def _clear_screen '{
     """
-    Summary
-    -------
     Clears the terminal screen
 
-    Description
-    -----------
-    Clears the screen without losing the screen history or messing up the
-    scrolling capabilities (this has been a problem for certain terminals)
-    by blanking out the entire height of the screen and returning the cursor to
-    the top left corner.
+    Description:
+
+      Clears the screen without losing the screen history or messing up the
+      scrolling capabilities (this has been a problem for certain terminals)
+      by blanking out the entire height of the screen with newlines and
+      returning the cursor to the top left corner.
+
+    Usage::
+
+      > _clear_screen
+
     """
 

specdomain/trunk/src/specdomain/comparison/conf.py

@@ -95 +95 @@
 # a list of builtin themes.
 html_theme = 'default'
+html_theme = 'agogo'
+html_theme = 'sphinxdoc'
 
 # Theme options are theme-specific and customize the look and feel of a theme

specdomain/trunk/src/specdomain/comparison/index.rst

@@ -9 +9 @@
 
 This is an example of documenting SPEC macro source code with Sphinx.
+
+.. seealso:: http://www.aps.anl.gov/Sectors/33_34/controls/spec/robodoc/auto_mac.html
 
 .. autospecdir:: ./

specdomain/trunk/src/specdomain/comparison/starter.py

@@ -7 +7 @@
 (and provides a way to use the source-code debugger for the process)
 '''
-
-import os
-import sphinx
-import sys
 
 import os

specdomain/trunk/src/specdomain/doc/bpm.mac

@@ -23 +23 @@
 
 
-Usage
-        ``qdo /epics/clients/spec/macros/bpm.mac``
+Usage::
+
+        qdo /epics/clients/spec/macros/bpm.mac
 """