source: specdomain/trunk/src/specdomain/doc/howto-markup.rst @ 1022

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

work-in-progress
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 12.4 KB
Line 
1.. $Id: howto-markup.rst 1022 2012-07-16 01:24:17Z jemian $
2
3==========================================================
4How to Markup a SPEC Macro File
5==========================================================
6
7#. start with SPEC macro file that is not marked up
8#. create a Sphinx documentation project
9#. apply markup
10#. test
11
12.. tip:: In addition to the Sphinx documentation (http://sphinx.pocoo.org),
13        a good reference how to document your macros can be found here:
14        http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx
15        but a Google search for *sphinx python docstrings examples* will turn up a wealth of alternatives.
16
17Basic SPEC Macro file
18==============================
19
20This example is a SPEC macro file from the APS subversion repository:
21https://subversion.xor.aps.anl.gov/spec/macros/trunk/common/hkl_ioc.mac
22because it is simple, brief, does not contain references to other
23macro files, provides its documentation in SPEC comments, and has not been
24marked up previously for documentation with Sphinx.  Here is the file
25*hkl_ioc.mac* in its entirety.
26
27.. literalinclude:: ex_markup/hkl_ioc.mac.original
28    :tab-width: 4
29    :linenos:
30    :language: guess
31
32
33
34Create a Sphinx Project
35==============================
36
37.. index:: in-source configuration
38.. tip:: Use an :ref:`in-source configuration`
39
40Make a project directory and change directory into it. 
41Copy the file above into this directory with the name *hkl_ioc.mac*.
42Then run::
43
44        sphinx-quickstart
45
46Take most of the defaults. 
47These are the non-defaults for the example project:
48
49========================================================================================  ========================
50prompt                                                                                    response
51========================================================================================  ========================
52``> Project name:``                                                                       **example**
53``> Author name(s):``                                                                     **SPEC Macro Writer**
54``> Project version:``                                                                    **1**
55``> autodoc: automatically insert docstrings from modules (y/N) [n]:``                    **y**
56``> viewcode: include links to the source code of documented Python objects (y/N) [n]:``  **y**
57========================================================================================  ========================
58
59Edit the document ``index.rst`` so it looks like this::
60
61        .. example documentation master file, created by
62           sphinx-quickstart on Sun Jul 15 17:54:46 2012.
63           You can adapt this file completely to your liking, but it should at least
64           contain the root `toctree` directive.
65       
66        Welcome to example's documentation!
67        ===================================
68       
69        .. autospecmacro:: hkl_ioc.mac
70       
71        Contents:
72       
73        .. toctree::
74           :maxdepth: 2
75       
76       
77       
78        Indices and tables
79        ==================
80       
81        * :ref:`genindex`
82        * :ref:`modindex`
83        * :ref:`search`
84       
85Edit *conf.py* and make these changes (in order):
86
87===================================================   ==============================
88change                                                location
89===================================================   ==============================
90``extensions.append( 'sphinxcontrib.specdomain' )``   insert *after* line 28
91===================================================   ==============================
92
93The result should look like this file: :download:`ex_markup/conf.py`.
94
95Apply Markup
96==============================
97
98.. tip:: We will edit the *hkl_ioc.mac* file now.
99        Before we start applying markup,
100        it's a good idea to make a backup copy of the original::
101       
102                cp hkl_ioc.mac  hkl_ioc.mac.original
103
104Here are the steps to consider when converting SPEC comments to reST markup.
105
106#. identify the SPEC comments
107#. extended comments (docstrings)
108   #. global docstring
109   #. macro docstring
110   #. others are ignored by Sphinx
111#. descriptive comments
112
113SPEC comments
114------------------
115
116Obvious as this sounds, it may help someone to see that the SPEC comments
117are on lines 1-32.  It is easy to place this entire block within an
118extended comment [#]_ (known hereafter as a *docstring*).  Make these
119additions to lines 1 and 32:
120
121=====  =============================================================================================
122line   new
123=====  =============================================================================================
1241      ``"""#===============================================================================``
12532     ``#==============================================================================="""``
126=====  =============================================================================================
127
128But this is not enough, as the content will look like a wreck.
129
130--------------------------
131
132        #===============================================================================
133        #**************SPEC macros for the Advanced Photon Source***********************
134        #===============================================================================
135        #
136        # Beamline/Sector: 4ID
137        #
138        # Macro Package: hkl_ioc.mac
139        #
140        # Version: 1.0 (August,2005)
141        #
142
143--------------------------
144
145... and so forth
146
147So, there is a choice to make.  Either:
148
149#. format the comment as literal text (least work)
150#. reformat the as reST. (more work, looks better)
151
152Literal text
153++++++++++++
154
155To format a SPEC comment as literal text, consider this brief SPEC comment:
156
157.. code-block:: guess
158        :linenos:
159       
160        # Summary: This macro scans the sample in a circular mesh.
161        #
162        # Dependencies: It is part of the circular mesh macro package.
163
164Its literal text rendition in reST is written:
165
166.. code-block:: guess
167        :linenos:
168       
169        """
170        ::
171       
172                # Summary: This macro scans the sample in a circular mesh.
173                #
174                # Dependencies: It is part of the circular mesh macro package.
175               
176        """
177
178which looks like:
179
180-------------------
181       
182        ::
183       
184                # Summary: This macro scans the sample in a circular mesh.
185                #
186                # Dependencies: It is part of the circular mesh macro package.
187
188-------------------
189
190Note that the two colons indicate literal text follows. 
191Both the blank line after the colons and the final blank line are required to avoid warnings.
192And, the entire comment must be indented at least one column to the right of the two colons.
193
194reST markup
195+++++++++++++
196
197In reST, the SPEC comment above might be written as two definition list items [#]_:
198
199.. code-block:: guess
200        :linenos:
201       
202        """
203        Summary
204            This macro scans the sample in a circular mesh.
205         
206        Dependencies
207            It is part of the circular mesh macro package.
208   
209        """
210
211which looks like:
212
213-------------------
214
215        Summary
216            This macro scans the sample in a circular mesh.
217         
218        Dependencies
219            It is part of the circular mesh macro package.
220
221-------------------
222
223(The final blank line is necessary to avoid warnings.)
224
225This markup does not look too complicated until we reach the *Modification history* 
226starting at line 23.  The content here might be coded as either literal text (above)
227or a reST table.  Since the table is easy *and* CVS is no longer used, we'll
228format it as a table.
229
230Consider this SPEC comment:
231
232.. code-block:: guess
233        :linenos:
234       
235        #Revision 1.3  2006/05/22 20:34:35  jiaox
236        #removed unsed lines in ioc_HKL.
237        #
238        #Revision 1.2  2006/05/11 17:46:31  jiaox
239        #Added CVS Log entry.
240       
241It might be put into a table [#]_ such as:
242
243.. code-block:: guess
244        :linenos:
245       
246        ========   ===================  =======  =====================================
247        Revision   date/time            author   remarks
248        ========   ===================  =======  =====================================
249        1.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
250        1.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
251        ========   ===================  =======  =====================================
252
253which looks like:
254
255-------------------
256
257========   ===================  =======  =====================================
258Revision   date/time            author   remarks
259========   ===================  =======  =====================================
2601.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
2611.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
262========   ===================  =======  =====================================
263
264-------------------
265
266
267
268Global Docstring
269-------------------------
270
271The convention is to treat the first docstring in a macro file as the *global docstring*.
272
273With these ideas in mind,
274here is the markup of the first 32 lines:
275
276.. code-block:: guess
277        :linenos:
278       
279        """
280        SPEC macros for the Advanced Photon Source
281       
282        Beamline/Sector
283                4ID
284       
285        Macro Package
286                hkl_ioc.mac
287       
288        Version
289                1.0 (August,2005)
290       
291        Description
292                A user defined calcHKL to write the current HKL postion to a
293                soft IOC. It requires spec softioc running.
294       
295        Written by
296                X. Jiao 08/08/2005
297         
298        Modified by:
299       
300        User macros
301                ioc_HKL -> to turn on/off the feature of putting HKL to shared
302                memory.
303       
304        Internal macros
305                ioc_put_HKL -> write HKL to the soft IOC
306       
307        Modification history:
308         
309        ========   ===================  =======  =====================================
310        Revision   date/time            author   remarks
311        ========   ===================  =======  =====================================
312        1.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
313        1.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
314        ========   ===================  =======  =====================================
315        """
316
317which (except for the section title which is hard to render in this document) looks like:
318
319-------------------
320
321Beamline/Sector
322        4ID
323
324Macro Package
325        hkl_ioc.mac
326
327Version
328        1.0 (August,2005)
329
330Description
331        A user defined calcHKL to write the current HKL postion to a
332        soft IOC. It requires spec softioc running.
333
334Written by
335        X. Jiao 08/08/2005
336 
337Modified by:
338
339User macros
340        ioc_HKL -> to turn on/off the feature of putting HKL to shared
341                           memory.
342
343Internal macros
344        ioc_put_HKL -> write HKL to the soft IOC
345
346Modification history:
347 
348========   ===================  =======  =====================================
349Revision   date/time            author   remarks
350========   ===================  =======  =====================================
3511.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
3521.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
353========   ===================  =======  =====================================
354
355-------------------
356
357
358Test
359-----------
360
361Be sure to test your changes as you progress, until you are confident with reST markup.
362The *make* process is efficient, only rebuilding the documentation from affected
363.rst souce file changes.  However, you might need to make sure changes in the .mac files
364cause documentation to be rebuilt.  It might be easier, although less efficient,
365to rebuild your documentation each time. 
366
367::
368       
369        make clean html
370
371
372This is usually very fast (seconds).
373
374
375Docstring markup in each macro definition
376---------------------------------------------
377
378Each of the macro definitions can be marked up to provide documentation with the definition.
379The convention is to supply a short one-line summary first, then additional information as appropriate.
380
381Consider the definition for ``ioc_HKL``. 
382A summary of it is given in the first comment section.
383We'll apply that as the docstring:
384
385.. code-block:: guess
386        :linenos:
387
388        def ioc_HKL '{
389            """to turn on/off the feature of putting HKL to shared memory."""
390             
391            if($# != 1) { eprint "Usage: ioc_HKL on/off ";exit}
392           
393           
394            if(("$1" == "on")) {
395               cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")
396               print "Now put HKL to softioc."
397               exit
398            }
399            if(("$1" == "off")) {
400               cdef("user_save_HKL","","ioc_HKL","delete")
401               print "Stop put HKL to softioc."
402               exit
403            }
404            eprint "Usage: ioc_HKL on/off "
405        }'
406
407Do the same thing for the *ioc_put_HKL* macro definition.
408
409
410-----------------
411
412.. rubric:: Footnotes
413
414.. [#] a SPEC :ref:`extended comment <spec-extended-comments>` is text that is surrounded by three
415       double-quote characters (``"""``), such as:
416       
417                """this is triple-quoted text is a docstring"""
418       
419       In the Python language, this is known as a docstring.
420       But, **unlike Python**, SPEC does not recognize single quotes
421       to mark extended comments.  Only use the double quote character.
422.. [#] definition list: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
423.. [#] table: http://sphinx.pocoo.org/rest.html#tables
Note: See TracBrowser for help on using the repository browser.