Example with more extensive reST markup

This example demonstrates how a file more extensive reST markup will be documented.:

.. autospecmacro:: bpm.mac

SPEC Macro File: bpm.mac

source code: bpm.mac

Macro support for a beam position monitor.

Purpose
Macro support for a beam position monitor. The BPM has a serial interface. This support uses the EPICS generic serial record as a communications channel.
Dependencies
These macros require:
EPICS
Experimental Physics and Industrial Control System, http://www.aps.anl.gov/epics
EPICS support for XBPM
The EPICS support for the X-ray Beam Position Monitor (XBPM) is needed to interface between the RS-232 connection on the XBPM and the EPICS IOC using an octal232 IP card. The software support consists of an EPICS generic serial record, an EPICS database, and a state notation language sequence program.
EPICS PV support prefix
The support prefix is ioc:xbpm (configurable in XBPM_PREFIX)

Usage:

qdo /epics/clients/spec/macros/bpm.mac
GX_FACTOR

constant declaration

X-axis calibration, mm/unit
GY_FACTOR

constant declaration

Y-axis calibration, mm/unit
XBPM_PREFIX

constant declaration

EPICS support prefix
BPM_read_diode(u'chan',)

def() macro function declaration

read current value from the named BPM channel

param character chan:
 channel letter (a, b, c, or d)

example:

value = BPM_read_diode("b")
BPM_set_defaults

def macro declaration

Set (or reset) proper default values on the XBPM.

Also, measure the dark signals at each amplifier gain scale (range) for each photodiode by calling BPM_setAllDarkSignals. This process takes about one minute. The software does not check to make sure that the beam is off so you should be sure that the shutter is closed during the time you run this macro. When finished, set the amplifier gain back to the value it had as this macro was started.

BPM_setDarkSignal(u'range',)

def() macro function declaration

measure and set the dark signal on each channel for the given amplifier range

param int range:
  0<=range<=5

Measure and set the dark signal for each photodiode amplifier at the selected amplifier gain scale (range). Report the findings as a spec comment.

range gain
0 350 nA
1 700 nA
2 1400 nA
3 7 uA
4 70 uA
5 700 uA
BPM_setAllDarkSignals

def macro declaration

measure and set the dark current for all amplifier ranges

Variable Declarations (bpm.mac)

objtype name start_line summary
constant GX_FACTOR 30 X-axis calibration, mm/unit
constant GY_FACTOR 31 Y-axis calibration, mm/unit
constant XBPM_PREFIX 32 EPICS support prefix

Macro Declarations (bpm.mac)

objtype name start_line end_line summary
def BPM_set_defaults 48 92 Set (or reset) proper default values on the XBPM.
def BPM_setAllDarkSignals 153 161 measure and set the dark current for all amplifier ranges

Function Macro Declarations (bpm.mac)

objtype name start_line end_line args summary
function def BPM_read_diode 34 46 chan read current value from the named BPM channel
function def BPM_setDarkSignal 94 151 range measure and set the dark signal on each channel for the given amplifier range