source: specdomain/trunk/src/specdomain/test/test_doc.rst @ 989

Last change on this file since 989 was 989, checked in by jemian, 10 years ago

refs #8, still need to understand how the index is configured in the domain

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 3.7 KB
Line 
1.. $Id: test_doc.rst 989 2012-07-02 20:13:44Z jemian $
2
3===============
4Acceptance Test
5===============
6
7If all links are valid, test is done successfully.
8
9
10Directives
11==========
12
13A *directive* can be used to define the anchor point of a reference.
14Index entries will point back to the *directive*.  If the item
15defined in the directive is not obtained from the source code,
16then define it here, like these.  All of these directives should
17have entries in an Index.
18
19SPEC Macros
20^^^^^^^^^^^
21
22.. spec:def:: def_macro content
23
24   :param arg: list of arguments is optional
25   :type arg: str
26
27   This is a standard SPEC macro definition.
28
29.. spec:def:: def_function(arguments)
30
31   :param str arguments: named argument(s) to this function
32
33.. spec:rdef:: rdef_macro content
34
35   This is a SPEC macro definition with symbols that are evaluated only at run-time.
36
37.. spec:cdef:: cdef("cdef_macro", "content", "cdef_part", flags)
38
39   :param str cdef_macro: one-word name (quoted string) for this macro chain
40   :param str content: SPEC code to be inserted (typically a single macro)
41   :param str cdef_part: name for this part of the chained macro
42   :param str flags: see the manual
43
44..
45        SPEC cdef macro definitions
46        ++++++++++++++++++++++++++++++++
47       
48        .. TODO: pull this subsection once this part is made to work
49       
50        There are several different signatures for SPEC's ``cdef`` macro definition.
51        Here are some examples pulled from the ``SPEC.D`` directory.
52       
53        .. note::  At present, the argument list from ``cdef`` macro definitions
54           is not being parsed or handled.  This will be fixed in a future revision.
55           
56        .. literalinclude:: cdef-examples.mac
57           :linenos:
58           :language: guess
59
60SPEC Variables
61^^^^^^^^^^^^^^
62
63These are some representative variable declarations in SPEC macro source files::
64
65        global  BCDA_GM[]
66       
67           global    theta[]
68           global    2theta[]  # this will not be found
69           global    _motor[]
70       
71        global kohzu_PV kohzuMV_PV UND_PV Und_Off UNDE_TRACK_ON
72        global       kohzuStop_PV kohzuMode_PV      kohzuMove_PV
73            global CCD_OVERHEAD_SECS_MEASURED   # measured readout time
74       
75            global @A_name[] @B_name[]
76               unglobal @A_name
77               unglobal @B_name
78
79Variables in Directives
80+++++++++++++++++++++++
81
82These define the variable.
83
84global variable declaration:
85
86        .. spec:global:: A[]
87       
88           ``A[]`` contains the values of all motors
89
90local variable declaration: 
91
92        .. spec:local:: i
93       
94           ``i`` is a local loop counter
95
96constant declaration: 
97
98        .. spec:local:: TWO_PI
99       
100           ``TWO_PI`` is the ratio of a circle's circumference to its diameter.
101
102array variable declaration:
103
104        *--tba--*
105
106Variables in Roles
107+++++++++++++++++++++++
108
109These items should link back to the directives above.
110
111* global variable declaration:  :spec:global:`A[]`
112* local variable declaration:   :spec:local:`i`
113* array variable declaration:   *--tba--*
114* constant declaration:                 :spec:constant:`TWO_PI`
115
116
117Roles
118=====
119
120A *role* refers to a *directive* (makes a link to a *directive* defined elsewhere).
121Each of these items should produce a valid link.  Additionally, every call to a
122*role* should produce an index entry.
123
124SPEC Macros
125^^^^^^^^^^^
126
127These items should link back to the directives above.
128
129* macro definition:                             :spec:def:`def_macro`
130* function definition:                          :spec:def:`def_function(arguments)`
131* runtime-defined macro definition: :spec:rdef:`rdef_macro`
132* chained macro definition:             :spec:cdef:`cdef("cdef_macro", "content", "cdef_part", flags)`
133
134SPEC Variables
135^^^^^^^^^^^^^^
136
137The SPEC macro language provides for several types of variable:
138
139* global variables, such as:    :spec:global:`A[]`
140* local variable, such as:      :spec:local:`i`
141* array variable declaration:   *--tba--*
142* constant declaration:                 :spec:constant:`TWO_PI`
143
144Source code documentation
145============================
146
147.. toctree::
148   :maxdepth: 2
149   :glob:
150
151   *.mac
Note: See TracBrowser for help on using the repository browser.