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

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

refs #8: finish the documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 9.1 KB
Line 
1.. $Id: spec.rst 1028 2012-07-16 06:06:58Z 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
71.. sidebar:: Do not use the single-quote character to mark an extended comment.
72
73        In the Python language, a triple-quoted string is known as a docstring.
74        But, **unlike Python**, SPEC does not recognize single quotes
75        to mark extended comments.  Only use the double quote character for SPEC files.
76
77Since 2002, SPEC has provided an *extended comment* block. [#]_
78Such a block begins and ends
79with three double-quotes, such as::
80
81        """This is an extended comment"""
82
83Here, the extended comment block should be formatted according to the conventions of
84restructured text [#]_.  There is also a
85:ref:`recommended convention <convention for extended comment>` 
86for using extended comments in SPEC macro files.
87
88
89
90Describing SPEC objects
91-----------------------------------
92
93The following *directives* refer to objects in SPEC macro source code files
94and create index entries and identifiers:
95
96.. rst:directive::  spec:def
97
98   Declare the name of a SPEC ``def`` macro.
99   
100   +---------------------------+--------------------------+
101   | ReST code                 | Displays like            |
102   +===========================+==========================+
103   | ::                        | .. spec:def:: demo_def   |
104   |                           |                          |
105   |   .. spec:def:: demo_def  |                          |
106   +---------------------------+--------------------------+
107
108.. rst:directive::  spec:rdef
109
110   Declare the name of a SPEC ``rdef`` run-time-defined macro.
111   
112   +-----------------------------+----------------------------+
113   | ReST code                   | Displays like              |
114   +=============================+============================+
115   | ::                          | .. spec:rdef:: demo_rdef   |
116   |                             |                            |
117   |   .. spec:rdef:: demo_rdef  |                            |
118   +-----------------------------+----------------------------+
119
120.. rst:directive::  spec:cdef
121
122   Declare the name of a SPEC ``cdef`` chained macro.
123   
124   +-------------------------------------+------------------------------------+
125   | ReST code                           | Displays like                      |
126   +=====================================+====================================+
127   | ::                                  | .. spec:cdef:: cdef("demo_cdef")   |
128   |                                     |                                    |
129   |   .. spec:cdef:: cdef("demo_cdef")  |                                    |
130   +-------------------------------------+------------------------------------+
131
132   More elaborate example showing how to call a
133   chained macro and also describe the arguments::
134   
135                .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
136                   
137                   :param str demo_cdef_more: name of chained macro
138                   :param str spec_code: SPEC code to be executed (usually a single macro name)
139                   :param str key: name of this part of the chained macro
140                   :param flags: see http://www.certif.com/spec_help/funcs.html
141                   :rtype: none
142                   
143                   This text is ignored (for now).
144   
145   Displays like:
146   
147   .. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
148
149           :param str demo_cdef_more: name of chained macro
150           :param str spec_code: SPEC code to be executed (usually a single macro name)
151           :param str key: name of this part of the chained macro
152           :param flags: see **SPEC** documentation for details
153           :rtype: none
154
155.. rst:directive::  spec:global
156
157   Declare the name of a SPEC global variable.
158   
159   +---------------------------------+--------------------------------+
160   | ReST code                       | Displays like                  |
161   +=================================+================================+
162   | ::                              | .. spec:global:: demo_global   |
163   |                                 |                                |
164   |   .. spec:global:: demo_global  |                                |
165   +---------------------------------+--------------------------------+
166
167.. rst:directive::  spec:local
168
169   Declare the name of a SPEC local variable.
170   
171   +--------------------------------+-------------------------------+
172   | ReST code                      | Displays like                 |
173   +================================+===============================+
174   | ::                             | .. spec:local:: demo_local    |
175   |                                |                               |
176   |   .. spec:local:: demo_local   |                               |
177   +--------------------------------+-------------------------------+
178
179.. rst:directive::  spec:constant
180
181   Declare the name of a SPEC constant.
182   
183   +-----------------------------------+----------------------------------+
184   | ReST code                         | Displays like                    |
185   +===================================+==================================+
186   | ::                                | .. spec:constant:: demo_const    |
187   |                                   |                                  |
188   |   .. spec:constant:: demo_const   |                                  |
189   +-----------------------------------+----------------------------------+
190
191
192.. _spec-roles:
193
194Cross-referencing SPEC objects
195-----------------------------------
196
197The following *roles* refer to objects in SPEC macro source code files
198and are possibly hyperlinked if a matching identifier is found:
199
200.. rst:role:: spec:def
201
202   Reference a SPEC macro definition by name. 
203   (Do not include the argument list.)
204   
205   ::
206   
207                An example ``def`` macro: :spec:def:`demo_def`
208               
209   An example ``def`` macro: :spec:def:`demo_def`
210
211.. rst:role:: spec:rdef
212
213   Reference a SPEC run-time macro definition by name. 
214   (Do not include the argument list.)
215   
216   ::
217   
218                An example ``rdef`` macro: :spec:rdef:`demo_rdef`
219
220   An example ``rdef`` macro: :spec:rdef:`demo_rdef`
221
222.. rst:role:: spec:cdef
223
224   Reference a SPEC chained macro definition by name. 
225   (Do not include the argument list.)
226   
227   ::
228   
229                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`
230                An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
231
232   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`.
233   An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.
234
235.. rst:role:: spec:global
236
237   Reference a global-scope variable.
238   
239   ::
240   
241                An example ``global`` variable: :spec:global:`demo_global`
242
243   An example ``global`` variable: :spec:global:`demo_global`
244   
245.. rst:role:: spec:local
246
247   Reference a local-scope variable.
248   
249   ::
250   
251                An example ``local`` variable: :spec:local:`demo_local`
252
253   An example ``local`` variable: :spec:local:`demo_local`
254   
255.. rst:role:: spec:constant
256
257   Reference a local-scope variable.
258   
259   ::
260   
261                An example ``local`` variable: :spec:constant:`demo_constant`
262
263   An example ``local`` variable: :spec:constant:`demo_constant`
264
265
266
267Undeclared Variables
268---------------------
269
270Undeclared variables (those with no formal global, local, constant, or
271array declaration) will not be documented.  At least for now.
272
273
274
275------------
276
277.. rubric:: Footnotes
278.. [#] *hidden* objects begin with one underline character, such as ``_hidden``
279.. [#] *anonymous* objects begin with at least two underline characters, such as ``__anon``
280.. [#] SPEC extended comments:  http://www.certif.com/spec_help/chg5_01.html
281.. [#] restructured text: http://docutils.sf.net/rst.html
282.. [#] For now, the rendition is basic.  This will be improved in a future revision.
Note: See TracBrowser for help on using the repository browser.