Changeset 1017

Timestamp:

Jul 15, 2012 8:45:39 AM (11 years ago)

Author:

jemian

Message:

fixes #11, always require whitespace after "def" or "rdef" when not a macro function

Location:

specdomain/trunk/src/specdomain

Files:

• comparison/auto.mac (modified) (33 diffs)
• doc/bugs.rst (modified) (1 diff)
• sphinxcontrib/specmacrofileparser.py (modified) (1 diff)

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

@@ -62 +62 @@
 ----------------------------------------
 The filter adjustment assures a high incident photon rate within a band
-just below the rate limit of the detector. The width of the band is defined
-by the step size in transmission, defined in AUTO_FILTER_FACTOR,
+just below the rate limit of the detector. The width of the band is
+defined by the step size in transmission, defined in AUTO_FILTER_FACTOR,
 which is used for each correction. If the count rate is higher than
 AUTO_RATE_LIMIT, the transmission is immediately reduced by
@@ -132 +132 @@
 
 No special configuration is needed to run these macros. Simply load the macro
-file and run :spec:def:`auto_setup`::
-
-  > qdo auto.mac
-  > auto_setup
+file and run ``auto_setup``::
+
+> qdo auto.mac
+> auto_setup
 
 Dependencies
@@ -142 +142 @@
 Dependencies on other macros:
 
-* :spec:macrofile:`filter.mac` (used to control the attenuators):
-
-  - :spec:def:`filter_trans`
-  - :spec:def:`filter_get_trans()`
-  - :spec:def:`filter_get_trans_up()`
-  - :spec:def:`filter_get_mask()`
-  - :spec:def:`filter_max()`
-
-* :spec:def:`recount` (modified count command used to retake an exposure)
+* filter.mac (used to control the attenuators):
+
+  - filter_trans
+  - filter_get_trans()
+  - filter_get_trans_up()
+  - filter_get_mask()
+  - filter_max()
+
+* recount (modified count command used to retake an exposure)
 
 Impact
@@ -156 +156 @@
 The following chained macro definitions are affected by this macro:
 
-* :spec:def:`user_prescan_head`
-* :spec:def:`user_chk_counts` (from our modified :spec:def:`count` command)
-* :spec:def:`user_precount`
+* user_prescan_head
+* user_chk_counts (provided in our modified ``count`` command)
+* user_precount
 
 File information
@@ -252 +252 @@
   SPHINX code documentation suite.
 
-2012/07/13 (CS):
-
-- renamed some private macros to start with underscores::
-
-    auto_precount        --> _auto_precount
-    auto_prescan_head    --> _auto_prescan_head
-    auto_user_chk_counts --> _auto_user_chk_counts
-
-- moved the macro definitions for the above macros out of the
-  :spec:def:`auto_set_level` macro to avoid unnecessary nested definitions.
-
-
 TO DO
 -----
@@ -270 +258 @@
 - complete documentation
 - insert hyperlinks into documentation
-
 """
 
-###############################################################################
+#==============================================================================
+
+#==============================================================================
 # Global variable definitions
-###############################################################################
-
-  global AUTO_MAC                 #: Save the name of this macro file
-  global AUTO_LEVEL               #: Type of adjustments {0,1,2}
-  global AUTO_MODE                #: Adjustment mode (pilot vs. post-exp) {0,1}
-  global AUTO_COUNTER             #: Counter to monitor
-  global AUTO_COUNT_RBV           #: Counter read back value (measured counts)
-  global AUTO_RETRY_MAX           #: Maximum number of retries
-  global AUTO_EXP_LOW             #: Low exposure time limit
-  global AUTO_EXP_HIGH            #: High exposure time limit
-  global AUTO_PILOT_EXPTIME       #: Exposure time for pilot exposures
-  global AUTO_RATE_LIMIT          #: High rate limit
-  global AUTO_COUNT_HIGH          #: High count limit
-  global AUTO_COUNT_TARGET        #: Target count level
-  global AUTO_COUNT_LOW           #: Low count limit
-  global AUTO_FILTER_FACTOR       #: Filter transmission factor for adjustments
-  global AUTO_COUNT_PREC          #: Count time precision (rounding)
-  global AUTO_FILTER_LOCK         #: Lock if rate-limited
-  global AUTO_SET_PILOT           #: Set pilot exposure time in user_precount
-  global AUTO_ORIG_EXPTIME        #: Save the original requested count time
-  global AUTO_DEBUG               #: Debug flag
+#==============================================================================
+
+  # Save the name of this macro file (Used for the help function).
+  global AUTO_MAC
+         AUTO_MAC = DOFILE
+
+  global AUTO_LEVEL                # Type of adjustments {0,1,2}
+  global AUTO_MODE                 # Adjustment mode (pilot/post-exp){0,1}
+  global AUTO_COUNTER              # Counter to monitor
+  global AUTO_COUNT_RBV            # Counter read back value (measured counts)
+  global AUTO_RETRY_MAX            # Maximum number of retries
+  global AUTO_EXP_LOW              # low exposure time limit
+  global AUTO_EXP_HIGH             # highexposure time limit
+  global AUTO_PILOT_EXPTIME        # exposure time for pilot exposures
+  global AUTO_RATE_LIMIT           # High rate limit
+  global AUTO_COUNT_HIGH           # High count limit
+  global AUTO_COUNT_TARGET         # Target count level
+  global AUTO_COUNT_LOW            # Low count limit
+  global AUTO_FILTER_FACTOR        # Filter transmission factor for adjustments
+  global AUTO_COUNT_PREC           # Count time precision (rounding)
+
+  global AUTO_FILTER_LOCK          # Lock if rate-limited
+  global AUTO_SET_PILOT            # Set pilot exposure time in user_precount
+  global AUTO_ORIG_EXPTIME         # save the original requested count time
+  global AUTO_DEBUG                # debug flag
 
   # set default values for global variables
-  AUTO_MAC = DOFILE
   AUTO_COUNTER = det
   AUTO_LEVEL = 0
@@ -317 +309 @@
   AUTO_DEBUG = 0
 
-
-###############################################################################
+#==============================================================================
 # Macro command definitions
-###############################################################################
+#==============================================================================
 
 #------------------------------------------------------------------------------
 # allow for misspelled help commands
-#def autohelp '{auto_help}'
+def autohelp 'auto_help'
 
 def auto_help '{
@@ -506 +497 @@
   Turn off any automatic filter and exposure adjustments.
 
-  USAGE::
+  Usage::
 
     > auto_off
 
-  NOTE:
-    This command is equivalent to ``auto_set_level 0``
-
-  SEE ALSO:
+  .. note:: This command is equivalent to ``auto_set_level 0``
+
+  .. seealso::
      :spec:def:`auto_set_level`,
      :spec:def:`auto_on`
@@ -527 +517 @@
 def auto_on '{
   """
-  Turn on automatic filter and exposure adjustments.
-
-  This macro is identical to :spec:def:`auto_set_level`. Please refer to the
-  :spec:def:`auto_set_level` documentation for more details.
-  """
-
+  See :spec:def:`auto_set_level`
+  """
 auto_set_level $*
 
@@ -542 +528 @@
   Set the level of automatic filter and exposure adjustments.
 
-  USAGE::
+  Usage::
 
     > auto_set_level [<level>]
     > auto_on [<level>]
-
-  If now arguement is given, the user is prompted for input. The argument
-  ``<level>`` can be one of the following:
-
-      =====  =================================================================
-      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::
+        where <level> can be one of the following:
+          0 - automatic filter and exposure OFF
+          1 - automatic filter ON, automatic exposure OFF
+          2 - automatic filter and exposure ON
+        if <level> is ommitted, the users is asked for input
+
+
+        ===== =================================================================
+        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
@@ -566 +556 @@
         turns on automatic filter adjustments (level 1)
 
-  NOTE:
-     :spec:def:`auto_set_level` and :spec:def:`auto_on` are equivalent to
-     each other.
-
-  SEE ALSO:
+  .. note::
+     ``auto_set_level`` and ``auto_on`` are equivalent to each other
+
+  .. seealso::
      :spec:def:`auto_off`
 
@@ -606 +595 @@
   }
 
+  #-------------------------------------------
+  # define necessary chained macro definitions
+
+  #--------------------
+  def auto_prescan_head \'
+  #   =================
+    # if automatic filter setting is active start scan with very low
+    # filter transmission
+    if(AUTO_LEVEL > 0){
+      AUTO_ORIG_EXPTIME = COUNT_TIME
+      filter_trans 1e-8
+      if(AUTO_LEVEL > 1){
+        # start with low exposure times
+        COUNT_TIME = AUTO_EXP_LOW
+        _ctime = COUNT_TIME
+      }
+    }
+    # add auto_cleanup to cleanup_once
+    cdef("cleanup_once","auto_cleanup; ", "auto_cleanup_once_key",0x20)
+  \'
+
+  #-----------------------
+  def auto_user_chk_counts \'
+  #   ====================
+    if(AUTO_LEVEL > 0){
+      # automatic filter and exposure setting (if activated)
+      success = _auto_adjust_redo()
+    }
+  \'
+
+  #----------------
+  def auto_precount \'
+  #   =============
+    if(AUTO_LEVEL > 0){
+      if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
+        # remember the original exposure time
+        AUTO_ORIG_EXPTIME = COUNT_TIME
+        # set the pilot exposure time
+        COUNT_TIME = AUTO_PILOT_EXPTIME
+        _ctime = COUNT_TIME
+        AUTO_SET_PILOT = 0
+      }
+    }
+  \'
+
+  #---------------
+  def auto_cleanup \'
+  #   ============
+    # drop in filters after finishing, since we do not know where we end up
+    # (center of a peak for dscan?)
+    AUTO_SET_PILOT = 1
+    AUTO_FILTER_LOCK = 0
+    if(AUTO_LEVEL > 0){
+      filter_trans 1e-8
+    }
+    cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
+  \'
+
+
   #--------------------------------------------
   # include necessary chained macro definitions
@@ -612 +660 @@
   if (AUTO_LEVEL > 0){
 
-    #: add _auto_prescan_head to user_prescan_head
-    cdef("user_prescan_head", "{_auto_prescan_head}; ", \
-         "auto_prescan_head_key", 0x10)
-
-    #: add _auto_user_chk_counts to user_chk_counts
-    cdef("user_chk_counts", "{_auto_user_chk_counts}; ", \
+    # add auto_prescan_head to user_prescan_head
+    cdef("user_prescan_head", "auto_prescan_head; ", "auto_prescan_head_key",\
+         0x10)
+
+    # add auto_user_chk_counts to user_chk_counts
+    cdef("user_chk_counts", "auto_user_chk_counts; ", \
          "auto_user_chk_counts_key")
 
-    #: add _auto_precount to user_precount
-    cdef("user_precount", "{_auto_precount}; ", "auto_precount_key", 0x10)
-
-    #: add _auto_cleanup to the end of user_scan_tail
-    cdef("user_scan_tail","{_auto_cleanup}; ", \
+    # add auto_precount to user_precount
+    cdef("user_precount", "auto_precount; ", "auto_precount_key", 0x10)
+
+    # add auto_cleanup to the end of user_scan_tail
+    cdef("user_scan_tail","auto_cleanup; ", \
          "auto_user_scan_tail_key",0x20)
+
   }
 
@@ -637 +686 @@
   if (AUTO_LEVEL < 1) {
 
-    #: remove _auto_prescan_head from user_prescan_head
+    # remove auto_prescan_head from user_prescan_head
     cdef("user_prescan_head", "", "auto_prescan_head_key", "delete")
 
-    #: remove _auto_user_chk_counts from user_chk_counts
+    # remove auto_user_chk_counts from user_chk_counts
     cdef("user_chk_counts", "", "auto_user_chk_counts_key", "delete")
 
-    #: remove _auto_precount from user_precount
+    # remove auto_precount from user_precount
     cdef("user_precount", "", "auto_precount_key", "delete")
 
-    #: remove _auto_cleanup from user_scan_tail
+    # remove auto_cleanup from user_scan_tail and cleanup_once
     cdef("user_scan_tail", "", "auto_user_scan_tail_key", "delete")
-    #: remove _auto_cleanup from cleanup_once
     cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
   }
@@ -662 +710 @@
   exposure time adjustments.
 
-  DESCRIPTION:
+  Description:
+
     Need some more details here...
 
-  USAGE::
+
+  Usage::
 
     > auto_set_mode [<mode>]
@@ -673 +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:
+  .. seealso::
+
     :spec:def:`auto_setup`
 
@@ -716 +767 @@
   adjustments.
 
-  USAGE::
+  Usage::
 
     > auto_set_exposure [<min> <max>]
@@ -722 +773 @@
         when called with no arguments, the user is prompted
 
-  EXAMPLE::
+  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
-          set the minimum exposure time to 1 sec and the maximum to 10 sec
 
   """
@@ -754 +811 @@
   Display the current auto settings.
 
-  USAGE::
+  Usage::
 
     > auto_show
@@ -800 +857 @@
   Display the current auto-level exposure settings.
 
-  USAGE::
+  Usage::
 
     > auto_show_exposure
@@ -812 +869 @@
 
 
-###############################################################################
+#==============================================================================
 # Internal macros
-###############################################################################
-
-#------------------------------------------------------------------------------
-def _auto_cleanup '{
-  """
-  Cleanup routine for automatic filter/exposure control
-  """
-
-  # drop in filters after finishing, since we do not know where we end up
-  # (center of a peak for dscan?)
-  AUTO_SET_PILOT = 1
-  AUTO_FILTER_LOCK = 0
-  if(AUTO_LEVEL > 0){
-    filter_trans 1e-10
-  }
-  #: remove _auto_cleanup_once from cleanup_once
-  cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
-}'
-
-
-#------------------------------------------------------------------------------
-def _auto_prescan_head '{
-  """
-  Prepare for automatic filter/exposure control before the start of a scan
-
-  This inserts filters with a transmission of 1e-10, sets some values in
-  the global variables and adds a cleanup routine to ``cleanup_once``.
-  """
-
-  # if automatic filter setting is active start scan with very low
-  # filter transmission
-  if(AUTO_LEVEL > 0){
-    AUTO_ORIG_EXPTIME = COUNT_TIME
-    filter_trans 1e-10
-    if(AUTO_LEVEL > 1){
-      # start with low exposure times
-      COUNT_TIME = AUTO_EXP_LOW
-      _ctime = COUNT_TIME
-    }
-  }
-  #: add _auto_cleanup to cleanup_once
-  cdef("cleanup_once","{_auto_cleanup}; ", "auto_cleanup_once_key",0x20)
-}'
-
-
-#------------------------------------------------------------------------------
-def _auto_user_chk_counts '{
-  """
-  Check if counts are valid and retake exposure if necessary.
-  """
-
-  if(AUTO_LEVEL > 0){
-    # automatic filter and exposure setting (if activated)
-    success = _auto_adjust_redo()
-  }
-}'
-
-
-#------------------------------------------------------------------------------
-def _auto_precount '{
-  """
-  Prepare for automatic filter/exposure control at beginning of count command.
-  """
-
-  if(AUTO_LEVEL > 0){
-    if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
-      # remember the original exposure time
-      AUTO_ORIG_EXPTIME = COUNT_TIME
-      # set the pilot exposure time
-      COUNT_TIME = AUTO_PILOT_EXPTIME
-      _ctime = COUNT_TIME
-      AUTO_SET_PILOT = 0
-    }
-  }
-}'
-
+#==============================================================================
 
 #------------------------------------------------------------------------------
 def _auto_print_setup '{
   """
-  Print the configuration options and current values to screen
-
-  NOTE:
+  Summary
+  -------
+  Prints the configuration options and current values to screen
+
+  .. note::
      The option numbers must be kept in sync between
      :spec:def:`_auto_set_option` and
@@ -935 +919 @@
 def _auto_set_option '{
   """
-  Sets a new value for a given option.
-
-  DESCRIPTION:
+  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 :spec:def:`_auto_print_setup` command.
 
-  NOTE:
-    The option numbers must be kept in sync between
-    :spec:def:`_auto_set_option` and
-    :spec:def:`_auto_print_setup`.
+  .. note::
+     The option numbers must be kept in sync between
+     :spec:def:`_auto_set_option` and
+     :spec:def:`_auto_print_setup`.
 
   """
@@ -1178 +1163 @@
   Analyze the previous exposure
 
-  DESCRIPTION:
+  Description:
+
     This macro retrieves the necessary information to analyze the last exposure
     and to initiate adjustments, if necessary. Usually, this step consists only
@@ -1186 +1172 @@
     etc.
 
-  USAGE::
+  Usage::
 
     > _auto_analyze_exposure
@@ -1202 +1188 @@
   Calculate and apply necessary exposure time and filter adjustments.
 
-  DESCRIPTION:
-
-    The function returns 1 if transmission or exposure time have been changed,
-    0 otherwise.
-
-  USAGE::
-    > changed = _auto_adjust()
+  Description:
+
+    The function returns 1 if transmission or exposure time are changed, 0
+    otherwise.
 
   """
@@ -1424 +1407 @@
   Make sure the user-entered exposure times are consistent
 
-  USAGE::
+  Usage::
 
     > _auto_check_exposure
@@ -1446 +1429 @@
   Make sure the user-entered count levels are consistent
 
-  USAGE::
+  Usage::
 
     > _auto_check_levels
@@ -1476 +1459 @@
   round it to the given count time precision.
 
-  USAGE::
+  Usage::
 
     > adjusted_time = _auto_calc_exposure(requested_time)
@@ -1503 +1486 @@
   Determines whether the auto-adjusting has been successful.
 
-  DESCRIPTION:
+  Description:
 
     If the current exposure does not meet the required criteria, counting
@@ -1510 +1493 @@
     The function returns 1 in case of success, 0 otherwise.
 
-  USAGE::
+  Usage::
 
     > success = _auto_adjust_redo()
 
-  NOTE:
-    This macro makes use of the :spec:def:`recount` macro, which has to be
-    added to SPEC during the startup procedure.
+  .. note::
+     This macro makes use of the :spec:def:`recount` macro, which has to be
+     added to SPEC during the startup procedure.
 
   """
@@ -1563 +1546 @@
     Clears the terminal screen
 
-    DESCRIPTION:
+    Description:
+
       Clears the screen without losing the screen history or messing up the
       scrolling capabilities (this has been a problem for certain terminals)
@@ -1569 +1553 @@
       returning the cursor to the top left corner.
 
-    USAGE::
+    Usage::
 
       > _clear_screen
@@ -1592 +1576 @@
 }
 
-###############################################################################
+#==============================================================================
 # End of $Id: $
-###############################################################################
+#==============================================================================

specdomain/trunk/src/specdomain/doc/bugs.rst

@@ -9 +9 @@
 * fix the signature recognition for roles
 * fix the signature handling for roles and directives
-* grep detection of macros fails for def declarations in extended comments (TRAC ticket #11)::
-
-        > I found the cause of the processing error. It must have something to do
-        > the the regex you use to identify definitions. Line 65 in the header
-        > docstring started with the word "defined". Somehow that triggered the
-        > regexp, which collected everything up to the next "(", which happens to be
-        > on line 69 "(2*AUTO_FILTER_FACTOR)".
-        > I temporarily fixed the problem by moving the word "defined" to the end of
-        > the previous line, but this fluke could potentially arise again. Is there
-        > a way of not searching for any of the function declarations (def, cdef,
-        > rdef, global, ...) inside a docstring? Otherwise, you may have to improve
-        > the regex.

specdomain/trunk/src/specdomain/sphinxcontrib/specmacrofileparser.py

@@ -87 +87 @@
                         string_start
                         + r'\s*?'                           # optional blank space
-                        + r'(r?def)'                        # 1: def_type (rdef | def)
+                        + r'(r?def)\s'                      # 1: def_type (rdef | def)
                         + non_greedy_whitespace
                         + macro_name_match                  # 2: macro_name