Changeset 1022


Ignore:
Timestamp:
Jul 15, 2012 8:24:17 PM (10 years ago)
Author:
jemian
Message:

work-in-progress

Location:
specdomain/trunk/src/specdomain/doc
Files:
2 added
3 edited

Legend:

Unmodified
Added
Removed
  • specdomain/trunk/src/specdomain/doc/ex_markup/hkl_ioc.mac

    r1021 r1022  
    1 #===============================================================================
    2 #**************SPEC macros for the Advanced Photon Source***********************
    3 #===============================================================================
    4 #
    5 # Beamline/Sector: 4ID
    6 #
    7 # Macro Package: hkl_ioc.mac
    8 #
    9 # Version: 1.0 (August,2005)
    10 #
    11 # Description: A user defined calcHKL to write the current HKL postion to a
    12 #              soft IOC. It requires spec softioc running.
    13 #
    14 # Written by: X. Jiao 08/08/2005
    15 #
    16 # Modified by:
    17 #
    18 # User macros: ioc_HKL -> to turn on/off the feature of putting HKL to shared
    19 #                           memory.
    20 #
    21 # Internal macros: ioc_put_HKL -> write HKL to the soft IOC
    22 #
    23 # Modification history:
    24 #
    25 #$Log$
    26 #Revision 1.3  2006/05/22 20:34:35  jiaox
    27 #removed unsed lines in ioc_HKL.
    28 #
    29 #Revision 1.2  2006/05/11 17:46:31  jiaox
    30 #Added CVS Log entry.
    31 #
    32 #===============================================================================
     1"""
     2SPEC macros for the Advanced Photon Source
     3
     4Beamline/Sector
     5        4ID
     6
     7Macro Package
     8        hkl_ioc.mac
     9
     10Version
     11        1.0 (August,2005)
     12
     13Description
     14        A user defined calcHKL to write the current HKL postion to a
     15        soft IOC. It requires spec softioc running.
     16
     17Written by
     18        X. Jiao 08/08/2005
     19 
     20Modified by:
     21
     22User macros
     23        ioc_HKL -> to turn on/off the feature of putting HKL to shared
     24                           memory.
     25
     26Internal macros
     27        ioc_put_HKL -> write HKL to the soft IOC
     28
     29Modification history:
     30 
     31========   ===================  =======  =====================================
     32Revision   date/time            author   remarks
     33========   ===================  =======  =====================================
     341.3        2006/05/22 20:34:35  jiaox    removed unsed lines in ioc_HKL.
     351.2        2006/05/11 17:46:31  jiaox    Added CVS Log entry.
     36========   ===================  =======  =====================================
     37"""
    3338
    3439#===============================================================================
     
    5762#===============================================================================
    5863def ioc_HKL '{
     64    """to turn on/off the feature of putting HKL to shared memory."""
    5965     
    6066    if($# != 1) { eprint "Usage: ioc_HKL on/off ";exit}
     
    7985#===============================================================================
    8086def ioc_put_HKL '
     87    """write HKL to the soft IOC"""
     88   
    8189    epics_put(sprintf("%s:H",SIOC_PV),H)
    8290    epics_put(sprintf("%s:K",SIOC_PV),K)
  • specdomain/trunk/src/specdomain/doc/howto-configure.rst

    r1013 r1022  
    44How to Create and Configure a Sphinx project to Document SPEC Macros
    55====================================================================
     6
     7.. tip:: for more information on this topic, refer to the SPhinx tutorial:
     8                        http://sphinx.pocoo.org/tutorial.html
    69
    710Decide which configuration
     
    1518                        Then again, maybe not.
    1619
    17 --tba--
    1820
    1921.. index:: ! in-source configuration
     22.. _in-source configuration:
    2023
    2124In-source configuration
  • specdomain/trunk/src/specdomain/doc/howto-markup.rst

    r1021 r1022  
    99#. apply markup
    1010#. 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.
    1116
    1217Basic SPEC Macro file
     
    1823macro files, provides its documentation in SPEC comments, and has not been
    1924marked up previously for documentation with Sphinx.  Here is the file
    20 ``hkl_ioc.mac`` in its entirety.
    21 
    22 .. literalinclude:: ex_markup/hkl_ioc.mac
     25*hkl_ioc.mac* in its entirety.
     26
     27.. literalinclude:: ex_markup/hkl_ioc.mac.original
    2328    :tab-width: 4
    2429    :linenos:
     
    3035==============================
    3136
    32 .. tip:: Use an *in-source* configuration
    33 .. make a reference to in-source
    34 
    35 --tba--
     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`.
    3694
    3795Apply Markup
    3896==============================
    3997
    40 #. normal SPEC comments
     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
    41107#. extended comments (docstrings)
    42108   #. global docstring
     
    45111#. descriptive comments
    46112
    47 --tba--
     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
    48357
    49358Test
    50359-----------
    51360
    52 --tba--
     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 TracChangeset for help on using the changeset viewer.