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

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

refs #8, finished documenting a complete example
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 14.8 KB
Line 
1.. $Id: howto-markup.rst 1027 2012-07-16 04:41:05Z 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:: ../markup_example/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. 
41(On my development system, this directory is called ``../markup_example``.)
42Copy the file above into this directory with the name *hkl_ioc.mac*.
43Then run::
44
45        sphinx-quickstart
46
47Take most of the defaults. 
48These are the non-defaults for the example project:
49
50========================================================================================  ================================
51prompt                                                                                    response
52========================================================================================  ================================
53``> Project name:``                                                                       **example**
54``> Author name(s):``                                                                     **SPEC Macro Writer**
55``> Project version:``                                                                    **1**
56``> autodoc: automatically insert docstrings from modules (y/N) [n]:``                    **y**
57``> viewcode: include links to the source code of documented Python objects (y/N) [n]:``  **y**
58========================================================================================  ================================
59
60Edit the document ``index.rst`` so it looks like this::
61
62        .. example documentation master file, created by
63           sphinx-quickstart on Sun Jul 15 17:54:46 2012.
64           You can adapt this file completely to your liking, but it should at least
65           contain the root `toctree` directive.
66       
67        Welcome to example's documentation!
68        ===================================
69       
70        .. autospecmacro:: hkl_ioc.mac
71       
72        Contents:
73       
74        .. toctree::
75           :maxdepth: 2
76       
77       
78       
79        Indices and tables
80        ==================
81       
82        * :ref:`genindex`
83        * :ref:`modindex`
84        * :ref:`search`
85       
86Edit *conf.py* and make these changes:
87
88===================================================   ==============================
89change                                                directions
90===================================================   ==============================
91``sys.path.insert(0, os.path.abspath('..'))``         *replace* line 19
92``extensions.append( 'sphinxcontrib.specdomain' )``   insert *after* line 28
93===================================================   ==============================
94
95The revised file should look like this file: :download:`../markup_example/conf.py`.
96
97Now, build the documentation by typing::
98
99    make html
100    firefox _build/html/index.html &
101
102You should expect a page that looks like this figure:
103
104.. figure:: example1.png
105    :alt: view of original hkl_ioc.mac HTML documentation
106
107    Documentation of the original **hkl_ioc.mac** file.
108
109
110Apply Markup
111==============================
112
113.. tip:: We will edit the *hkl_ioc.mac* file now.
114        Before we start applying markup,
115        it's a good idea to make a backup copy of the original::
116       
117                cp hkl_ioc.mac  hkl_ioc.mac.original
118
119Here are the steps to consider when converting SPEC comments to reST markup.
120
121#. identify the SPEC comments
122#. extended comments (docstrings)
123   #. global docstring
124   #. macro docstring
125   #. others are ignored by Sphinx
126#. descriptive comments
127
128SPEC comments
129------------------
130
131Obvious as this sounds, it may help someone to see that the SPEC comments
132are on lines 1-32.  It is easy to place this entire block within an
133extended comment [#]_ (known hereafter as a *docstring*).  Make these
134additions to lines 1 and 32:
135
136=====  =============================================================================================
137line   new
138=====  =============================================================================================
1391      ``"""#===============================================================================``
14032     ``#==============================================================================="""``
141=====  =============================================================================================
142
143But this is not enough, as the content will look like a wreck.
144
145--------------------------
146
147        #===============================================================================
148        #**************SPEC macros for the Advanced Photon Source***********************
149        #===============================================================================
150        #
151        # Beamline/Sector: 4ID
152        #
153        # Macro Package: hkl_ioc.mac
154        #
155        # Version: 1.0 (August,2005)
156        #
157
158--------------------------
159
160... and so forth
161
162So, there is a choice to make.  Either:
163
164#. format the comment as literal text (least work)
165#. reformat the as reST. (more work, looks better)
166
167Literal text
168++++++++++++
169
170To format a SPEC comment as literal text, consider this brief SPEC comment:
171
172.. code-block:: guess
173        :linenos:
174       
175        # Summary: This macro scans the sample in a circular mesh.
176        #
177        # Dependencies: It is part of the circular mesh macro package.
178
179Its literal text rendition in reST is written:
180
181.. code-block:: guess
182        :linenos:
183       
184        """
185        ::
186       
187                # Summary: This macro scans the sample in a circular mesh.
188                #
189                # Dependencies: It is part of the circular mesh macro package.
190               
191        """
192
193which looks like:
194
195-------------------
196       
197        ::
198       
199                # Summary: This macro scans the sample in a circular mesh.
200                #
201                # Dependencies: It is part of the circular mesh macro package.
202
203-------------------
204
205Note that the two colons indicate literal text follows. 
206Both the blank line after the colons and the final blank line are required to avoid warnings.
207And, the entire comment must be indented at least one column to the right of the two colons.
208
209reST markup
210+++++++++++++
211
212In reST, the SPEC comment above might be written as two definition list items [#]_:
213
214.. code-block:: guess
215        :linenos:
216       
217        """
218        Summary
219            This macro scans the sample in a circular mesh.
220         
221        Dependencies
222            It is part of the circular mesh macro package.
223   
224        """
225
226which looks like:
227
228-------------------
229
230        Summary
231            This macro scans the sample in a circular mesh.
232         
233        Dependencies
234            It is part of the circular mesh macro package.
235
236-------------------
237
238(The final blank line is necessary to avoid warnings.)
239
240This markup does not look too complicated until we reach the *Modification history* 
241starting at line 23.  The content here might be coded as either literal text (above)
242or a reST table.  Since the table is easy *and* CVS is no longer used, we'll
243format it as a table.
244
245Consider this SPEC comment:
246
247.. code-block:: guess
248        :linenos:
249       
250        #Revision 1.3  2006/05/22 20:34:35  jiaox
251        #removed unsed lines in ioc_HKL.
252        #
253        #Revision 1.2  2006/05/11 17:46:31  jiaox
254        #Added CVS Log entry.
255       
256It might be put into a table [#]_ such as:
257
258.. code-block:: guess
259        :linenos:
260       
261        ========   ===================  =======  =====================================
262        Revision   date/time            author   remarks
263        ========   ===================  =======  =====================================
264        1.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
265        1.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
266        ========   ===================  =======  =====================================
267
268which looks like:
269
270-------------------
271
272========   ===================  =======  =====================================
273Revision   date/time            author   remarks
274========   ===================  =======  =====================================
2751.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
2761.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
277========   ===================  =======  =====================================
278
279-------------------
280
281
282
283Global Docstring
284-------------------------
285
286The convention is to treat the first docstring in a macro file as the *global docstring*.
287
288With these ideas in mind,
289here is the markup of the first 32 lines:
290
291.. code-block:: guess
292        :linenos:
293       
294        """
295        SPEC macros for the Advanced Photon Source
296       
297        Beamline/Sector
298                4ID
299       
300        Macro Package
301                hkl_ioc.mac
302       
303        Version
304                1.0 (August,2005)
305       
306        Description
307                A user defined calcHKL to write the current HKL postion to a
308                soft IOC. It requires spec softioc running.
309       
310        Written by
311                X. Jiao 08/08/2005
312         
313        Modified by:
314       
315        User macros
316                ioc_HKL -> to turn on/off the feature of putting HKL to shared
317                memory.
318       
319        Internal macros
320                ioc_put_HKL -> write HKL to the soft IOC
321       
322        Modification history:
323         
324        ========   ===================  =======  =====================================
325        Revision   date/time            author   remarks
326        ========   ===================  =======  =====================================
327        1.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
328        1.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
329        ========   ===================  =======  =====================================
330        """
331
332which (except for the section title which is hard to render in this document) looks like:
333
334-------------------
335
336Beamline/Sector
337        4ID
338
339Macro Package
340        hkl_ioc.mac
341
342Version
343        1.0 (August,2005)
344
345Description
346        A user defined calcHKL to write the current HKL postion to a
347        soft IOC. It requires spec softioc running.
348
349Written by
350        X. Jiao 08/08/2005
351 
352Modified by:
353
354User macros
355        ioc_HKL -> to turn on/off the feature of putting HKL to shared
356                           memory.
357
358Internal macros
359        ioc_put_HKL -> write HKL to the soft IOC
360
361Modification history:
362 
363========   ===================  =======  =====================================
364Revision   date/time            author   remarks
365========   ===================  =======  =====================================
3661.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
3671.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
368========   ===================  =======  =====================================
369
370-------------------
371
372
373Test
374-----------
375
376Be sure to test your changes as you progress, until you are confident with reST markup.
377The *make* process is efficient, only rebuilding the documentation from affected
378.rst souce file changes.  Usually, this also considers changes in the .mac files.
379This command is usually all it takes to rebuild the HTML documentation::
380
381        make html
382
383However, you might wish to make sure changes in the .mac files
384cause documentation to be rebuilt.  It might be easier, although less efficient,
385to rebuild your HTML documentation each time using this command::
386       
387        make clean html
388
389The builds are usually very fast (seconds).
390
391
392Docstring markup in each macro definition
393---------------------------------------------
394
395Each of the macro definitions can be marked up to provide documentation with the definition.
396The convention is to supply a short one-line summary first, then additional information as appropriate.
397
398Consider the definition for ``ioc_HKL``. 
399A summary of it is given in the first comment section.
400We'll apply that as the docstring:
401
402.. code-block:: guess
403        :linenos:
404
405        def ioc_HKL '{
406            """to turn on/off the feature of putting HKL to shared memory."""
407             
408            if($# != 1) { eprint "Usage: ioc_HKL on/off ";exit}
409           
410           
411            if(("$1" == "on")) {
412               cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")
413               print "Now put HKL to softioc."
414               exit
415            }
416            if(("$1" == "off")) {
417               cdef("user_save_HKL","","ioc_HKL","delete")
418               print "Stop put HKL to softioc."
419               exit
420            }
421            eprint "Usage: ioc_HKL on/off "
422        }'
423
424Do the same thing for the *ioc_put_HKL* macro definition.
425
426Document the global variable
427----------------------------------
428
429On line 45 (in the original file), there is a global variable declaration: ``global SIOC_PV``.
430The description for this variable has been deduced from its usage in this file with EPICS.  [#]_
431It is possible to document :spec:global:`SIOC_PV` using a :ref:`descriptive comment`.
432Insert the line containing ``global SIOC_PV`` with this one::
433
434        global SIOC_PV             ;#: soft IOC PV name
435
436The semicolon is used to ensure that the spec command is finished.  It might be unnecessary.
437The descriptive comment can be used *in-line* to define the item on that line.
438
439Similarly, add another :ref:`descriptive comment` to document line 38 (original file) by inserting this
440line *before* the line that reads ``cdef("user_save_HKL","","ioc_HKL")``::
441
442        #: preload check/setting here
443       
444Here the descriptive comment appearing on one line will provide a summary
445for the item defined on the next line only.
446
447Final Results
448=================
449
450Rebuild the completed :download:`../markup_example/hkl_ioc.mac` documentation with::
451
452        make html
453
454.. note:: Don't be concerned about the warnings of
455        ``SEVERE: Duplicate ID: "cdef-user_save_HKL".``
456        These messages are only informative. 
457        This :ref:`bug <bugs>` should be resolved in a future version of ``specdomain``.
458
459After refreshing the page in the WWW browser, it should like this:
460
461.. figure:: example2.png
462    :alt: view of marked-up hkl_ioc.mac HTML documentation
463
464    Documentation of the marked-up **hkl_ioc.mac** file.
465
466and the index will look like:
467
468.. figure:: example3.png
469    :alt: index of marked-up hkl_ioc.mac HTML documentation
470
471    Index of the marked-up **hkl_ioc.mac** file.
472
473.. note::  It is :ref:`planned for the future <todo>` to provide options for sorting the output alphabetically
474        and to provide other features.
475
476-----------------
477
478.. rubric:: Footnotes
479
480.. [#] a SPEC :ref:`extended comment <spec-extended-comments>` is text that is surrounded by three
481       double-quote characters (``"""``), such as:
482       
483                """this triple-quoted text is a docstring"""
484       
485       In the Python language, this is known as a docstring.
486       But, **unlike Python**, SPEC does not recognize single quotes
487       to mark extended comments.  Only use the double quote character.
488.. [#] definition list: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
489.. [#] table: http://sphinx.pocoo.org/rest.html#tables
490.. [#] EPICS: http://www.aps.anl.gov/epics
Note: See TracBrowser for help on using the repository browser.