source: specdomain/trunk/src/specdomain/doc/spec.rst @ 995

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

refs #8, bring this up to date

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 10.4 KB
Line 
1.. $Id: spec.rst 995 2012-07-06 21:11:36Z jemian $
2
3.. TODO: rewrite this from a SPEC macro authors viewpoint.
4        This reads from a SPHINX domain author's viewpoint.
5       
6        Note that most authors will not need the documentation primitives but rather just the
7        *autospecmacro* and *autospecdir* directives.
8
9Documenting SPEC Code
10========================
11
12.. _spec-directives:
13
14
15.. _spec-autospecdir:
16.. index:: ! autospecdir
17
18Documenting SPEC File Directories
19-----------------------------------
20
21.. rst:directive:: .. autospecdir:: path
22
23        :param str path: path (absolute or relative to the .rst file)
24                to an accessible directory with SPEC macro files
25   
26        ::
27   
28                .. autospecdir:: /home/user/spec.d/macros
29               
30        .. note::  options planned for future versions:
31
32                * document all subdirectories of *path*
33                * match files by a pattern (? glob *v.* re ?)
34
35   
36
37.. _spec-autospecmacro:
38.. index:: ! autospecmacro
39
40Documenting SPEC Files
41-----------------------------------
42
43.. rst:directive:: .. autospecmacro:: filename
44
45        :param str filename: name (with optional path) of the SPEC macro file.
46                The path component can be relative or absolute.  If relative,
47                the path is relative to the *.rst* file.
48
49        Document the contents of a SPEC macro source code file, including extended comments,
50        *def*, *rdef*, and *cdef* macro declarations and changes, and *local*,
51        *global*, and *constant* variable declarations.
52   
53        ::
54   
55                .. autospecmacro:: sixc.mac
56               
57        .. note::  options planned for future versions:
58
59                * standard documentation pattern
60                * include all extended comments
61                * ignore :index:`hidden objects` [#]_
62                * ignore :index:`anonymous objects` [#]_
63
64
65.. _spec-extended-comments:
66.. index:: ! extended comments
67
68SPEC Extended Comments
69--------------------------------
70
71Since 2002, SPEC has provided an *extended comment* block. [#]_
72Such a block begins and ends
73with three double-quotes, such as::
74
75        """This is an extended comment"""
76
77Here, the extended comment block should be formatted according to the conventions of
78restructured text [#]_.
79
80
81Describing SPEC objects
82-----------------------------------
83
84The following *directives* refer to objects in SPEC macro source code files
85and create index entries and identifiers:
86
87.. rst:directive::  spec:def
88
89   Declare the name of a SPEC ``def`` macro.
90   
91   +---------------------------+--------------------------+
92   | ReST code                 | Displays like            |
93   +===========================+==========================+
94   | ::                        | .. spec:def:: demo_def   |
95   |                           |                          |
96   |   .. spec:def:: demo_def  |                          |
97   +---------------------------+--------------------------+
98
99.. rst:directive::  spec:rdef
100
101   Declare the name of a SPEC ``rdef`` run-time-defined macro.
102   
103   +-----------------------------+----------------------------+
104   | ReST code                   | Displays like              |
105   +=============================+============================+
106   | ::                          | .. spec:rdef:: demo_rdef   |
107   |                             |                            |
108   |   .. spec:rdef:: demo_rdef  |                            |
109   +-----------------------------+----------------------------+
110
111.. rst:directive::  spec:cdef
112
113   Declare the name of a SPEC ``cdef`` chained macro.
114   
115   +-------------------------------------+------------------------------------+
116   | ReST code                           | Displays like                      |
117   +=====================================+====================================+
118   | ::                                  | .. spec:cdef:: cdef("demo_cdef")   |
119   |                                     |                                    |
120   |   .. spec:cdef:: cdef("demo_cdef")  |                                    |
121   +-------------------------------------+------------------------------------+
122
123   More elaborate example showing how to call a
124   chained macro and also describe the arguments::
125   
126                .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
127                   
128                   :param str demo_cdef_more: name of chained macro
129                   :param str spec_code: SPEC code to be executed (usually a single macro name)
130                   :param str key: name of this part of the chained macro
131                   :param flags: see http://www.certif.com/spec_help/funcs.html
132                   :rtype: none
133                   
134                   This text is ignored (for now).
135   
136   Displays like:
137   
138   .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
139
140           :param str demo_cdef_more: name of chained macro
141           :param str spec_code: SPEC code to be executed (usually a single macro name)
142           :param str key: name of this part of the chained macro
143           :param flags: see **SPEC** documentation for details
144           :rtype: none
145
146.. rst:directive::  spec:global
147
148   Declare the name of a SPEC global variable.
149   
150   +---------------------------------+--------------------------------+
151   | ReST code                       | Displays like                  |
152   +=================================+================================+
153   | ::                              | .. spec:global:: demo_global   |
154   |                                 |                                |
155   |   .. spec:global:: demo_global  |                                |
156   +---------------------------------+--------------------------------+
157
158.. rst:directive::  spec:local
159
160   Declare the name of a SPEC local variable.
161   
162   +--------------------------------+-------------------------------+
163   | ReST code                      | Displays like                 |
164   +================================+===============================+
165   | ::                             | .. spec:local:: demo_local    |
166   |                                |                               |
167   |   .. spec:local:: demo_local   |                               |
168   +--------------------------------+-------------------------------+
169
170.. rst:directive::  spec:constant
171
172   Declare the name of a SPEC constant.
173   
174   +-----------------------------------+----------------------------------+
175   | ReST code                         | Displays like                    |
176   +===================================+==================================+
177   | ::                                | .. spec:constant:: demo_const    |
178   |                                   |                                  |
179   |   .. spec:constant:: demo_const   |                                  |
180   +-----------------------------------+----------------------------------+
181
182
183.. _spec-roles:
184
185Cross-referencing SPEC objects
186-----------------------------------
187
188The following *roles* refer to objects in SPEC macro source code files
189and are possibly hyperlinked if a matching identifier is found:
190
191.. rst:role:: spec:def
192
193   Reference a SPEC macro definition by name. 
194   (Do not include the argument list.)
195   
196   ::
197   
198                An example ``def`` macro: :spec:def:`demo_def`
199               
200   An example ``def`` macro: :spec:def:`demo_def`
201
202.. rst:role:: spec:rdef
203
204   Reference a SPEC run-time macro definition by name. 
205   (Do not include the argument list.)
206   
207   ::
208   
209                An example ``rdef`` macro: :spec:rdef:`demo_rdef`
210
211   An example ``rdef`` macro: :spec:rdef:`demo_rdef`
212
213.. rst:role:: spec:cdef
214
215   Reference a SPEC chained macro definition by name. 
216   (Do not include the argument list.)
217   
218   ::
219   
220                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`
221                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
222
223   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`.
224   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
225
226.. rst:role:: spec:global
227
228   Reference a global-scope variable.
229   
230   ::
231   
232                An example ``global`` variable: :spec:global:`demo_global`
233
234   An example ``global`` variable: :spec:global:`demo_global`
235   
236.. rst:role:: spec:local
237
238   Reference a local-scope variable.
239   
240   ::
241   
242                An example ``local`` variable: :spec:local:`demo_local`
243
244   An example ``local`` variable: :spec:local:`demo_local`
245   
246.. rst:role:: spec:constant
247
248   Reference a local-scope variable.
249   
250   ::
251   
252                An example ``local`` variable: :spec:constant:`demo_constant`
253
254   An example ``local`` variable: :spec:constant:`demo_constant`
255
256
257
258Undeclared Variables
259---------------------
260
261Undeclared variables (those with no formal global, local, constant, or
262array declaration) will not be documented.  At least for now.
263
264
265Common Conventions
266====================
267
268There are several conventions to help provide consistency.
269These are not requirements.
270
271extended comments
272-----------------
273
274Only the first extended comment in a "section" should be documented.
275(This setting could be changed with an optional switch.)
276
277A "section" might be the global scope of a .mac file or a macro definition block.
278
279As much as possible, use the python documentation style (that is,
280first comment is module documentation, first comment inside
281macro definition is the macro documentation).
282
283hidden objects
284----------------
285
286*Hidden* objects begin with at least one underline character,
287such as ``_hidden``.  This includes macros and variables.
288These should be optional in the documentation.
289
290*Anonymous* objects begin with at least two underline characters,
291such as ``___anon``.  This includes macros and variables.
292These should not be documented unless specifically requested and
293only then if hidden objects are documented.
294
295undeclared variables
296---------------------
297
298Undeclared variables (those with no formal global, local, constant,
299or array declaration) will not be documented.  At least for now.
300
301parameter descriptions
302----------------------------
303
304Use the same syntax as parameter declarations for Python modules. 
305Here is an example SPEC macro with reST markup::
306
307        def my_comment '{
308            '''
309            Make a comment
310           
311            usage: ``my_comment "AR aligned to 15.14063 degrees"``
312           
313            :param str text: message to be printed
314            '''
315            qcomment "%s" $1
316        }'
317
318which documentation looks like this:
319
320.. spec:def:: my_comment text
321           
322            Make a comment
323           
324            usage: ``my_comment "AR aligned to 15.14063 degrees"``
325           
326            :param str text: message to be printed
327
328------------
329
330.. rubric:: Footnotes
331.. [#] *hidden* objects begin with one underline character, such as ``_hidden``
332.. [#] *anonymous* objects begin with at least two underline characters, such as ``__anon``
333.. [#] SPEC extended comments:  http://www.certif.com/spec_help/chg5_01.html
334.. [#] restructured text: http://docutils.sf.net/rst.html
335.. [#] For now, the rendition is basic.  This will be improved in a future revision.
Note: See TracBrowser for help on using the repository browser.