source: specdomain/src/specdomain/test/test_doc.rst @ 953

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

to progress with the *autodoc* feature for specdomain, need a SPEC macro file parser class that records line numbers and other desired info

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 4.4 KB
Line 
1.. $Id: test_doc.rst 953 2012-06-20 18:24:14Z 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   
44SPEC cdef macro definitions
45++++++++++++++++++++++++++++++++
46
47.. TODO: pull this subsection once this part is made to work
48
49There are several different signatures for SPEC's ``cdef`` macro definition.
50Here are some examples pulled from the ``SPEC.D`` directory.
51
52.. note::  At present, the argument list from ``cdef`` macro definitions
53   is not being parsed or handled.  This will be fixed in a future revision.
54   
55.. literalinclude:: cdef-examples.mac
56   :linenos:
57   :language: guess
58
59SPEC Variables
60^^^^^^^^^^^^^^
61
62These are some representative variable declarations in SPEC macro source files::
63
64        global  BCDA_GM[]
65       
66           global    theta[]
67           global    2theta[]  # this will not be found
68           global    _motor[]
69       
70        global kohzu_PV kohzuMV_PV UND_PV Und_Off UNDE_TRACK_ON
71        global       kohzuStop_PV kohzuMode_PV      kohzuMove_PV
72            global CCD_OVERHEAD_SECS_MEASURED   # measured readout time
73       
74            global @A_name[] @B_name[]
75               unglobal @A_name
76               unglobal @B_name
77
78Variables in Directives
79+++++++++++++++++++++++
80
81global variable declaration:
82
83.. spec:global:: A[]
84
85   ``A[]`` contains the values of all motors
86
87local variable declaration: 
88
89.. spec:local:: i
90
91   ``i`` is a local loop counter
92
93array variable declaration:
94
95        tba
96
97Variables in Roles
98+++++++++++++++++++++++
99
100* global variable declaration: :spec:global:`A[]`
101* local variable declaration:  :spec:local:`i`
102* array variable declaration:
103* constant declaration:
104
105Python example
106^^^^^^^^^^^^^^
107
108.. py:function:: python_function(t = None)
109
110   :param t: time_t object or None (defaults to ``now()``)
111   :type  t: str
112
113
114Roles
115=====
116
117A *role* refers to a *directive* (makes a link to a *directive* defined elsewhere).
118Each of these items should produce a valid link.  Additionally, every call to a
119*role* should produce an index entry.
120
121SPEC Macros
122^^^^^^^^^^^
123
124* macro definition: :spec:def:`def_macro`
125* function definition: :spec:def:`def_function(arguments)`
126* runtime-defined macro definition: :spec:rdef:`rdef_macro`
127* chained macro definition: :spec:cdef:`cdef("cdef_macro", "content", "cdef_part", flags)`
128
129SPEC Variables
130^^^^^^^^^^^^^^
131
132The SPEC macro language provides for several types of variable:
133
134* global variables, such as:  :spec:global:`A[]`
135* local variable, such as:  :spec:local:`i`
136* array variable declaration:
137* constant declaration:
138
139Source code documentation
140============================
141
142Python example
143^^^^^^^^^^^^^^
144
145See the python method :py:func:`python_function()` (defined above)
146
147..  This should document the Python module supporting the specdomain
148
149.. py:function:: test.testdoc.radius(x, y)
150        :noindex:
151       
152        :param float x: ordinate
153        :param float y: abcissa
154        :returns float: hypotenuse
155       
156        return math.sqrt(x*x + y*y)
157       
158        The radius function is based on an algorithm of Pythagorus.
159       
160        .. note:: The Pythagorean theorem was also cited in the movie *The Wizard of Oz*.
161
162:class:`SpecVariableObject` (Python Module)
163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
164
165.. autoclass:: sphinxcontrib.specdomain.SpecVariableObject
166    :members:
167    :undoc-members:
168    :show-inheritance:
169
170.. automodule:: sphinxcontrib.specdomain
171    :members:
172
173
174
175SPEC macro source file: ``cdef-examples.mac``
176^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177
178.. spec:macrofile:: cdef-examples.mac
179
180
181SPEC macro source file: ``test-battery.mac``
182^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183
184.. spec:macrofile:: test-battery.mac
Note: See TracBrowser for help on using the repository browser.