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

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

refs #8, much, MUCH better reporting, almost ready for release, need to improve the "howto" documentation in the docs/ subdir

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 8.7 KB
Line 
1.. $Id: spec.rst 1007 2012-07-12 22:56:32Z 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
265
266------------
267
268.. rubric:: Footnotes
269.. [#] *hidden* objects begin with one underline character, such as ``_hidden``
270.. [#] *anonymous* objects begin with at least two underline characters, such as ``__anon``
271.. [#] SPEC extended comments:  http://www.certif.com/spec_help/chg5_01.html
272.. [#] restructured text: http://docutils.sf.net/rst.html
273.. [#] For now, the rendition is basic.  This will be improved in a future revision.
Note: See TracBrowser for help on using the repository browser.