Changeset 1091


Ignore:
Timestamp:
Sep 5, 2012 9:29:02 AM (10 years ago)
Author:
cschlep
Message:

Minor work on the style guide

File:
1 edited

Legend:

Unmodified
Added
Removed
  • specdomain/trunk/src/specdomain/doc/style_guide.rst

    r1090 r1091  
    8080  to process the docstring::
    8181 
    82     global TTH            #: The scattering angle two-theta.
     82    global TTH            #: The scattering angle two-theta [float].
    8383
    8484    #: Clear the ccd shutter handler
    8585    rdef ccdset_shutter ''
    8686
    87     def do_nothing() ''   #: This macro does do anything.
     87    def do_nothing() ''   #: This macro does not do anything.
    8888
    8989
     
    128128------------
    129129The macro file header docstring provides information about the macro file as a
    130 whole (in the python world, this might be called a module).
     130whole (in the python world, this might be called a *module*).
    131131
    132132As with any docstring, the first item should be a concise summary line of what
     
    144144to meet the particular requirements of individual macro files:
    145145
    146 Description (top-level header):
     146**Description (top-level header)**:
    147147  A more elaborate description of the functionality provided in the macro file.
    148148  Include any number of subsections and subsubsections.
    149149
    150 Notes (top-level header):
     150**Notes (top-level header)**:
    151151  Any additional notes or comments about the file or its usage.
    152152 
    153 Installation (top-level header):
     153**Installation (top-level header)**:
    154154  Information on how to set up the macro functionality. This includes,
    155155  if applicable, the following subsections (second level headers):
    156156 
    157   Configuration:
     157  **Configuration**:
    158158    Prerequisites in the SPEC configuration. For example, the configuration of
    159159    dedicated counters may be necessary in order to use the macros.
    160160
    161   Setup:
     161  **Setup**:
    162162    The steps necessary to set up the macro functionality. For example, loading
    163163    the macro file (``qdo``) and running the ``macro_init`` function.
    164164
    165   Dependencies:
     165  **Dependencies**:
    166166    List all the dependencies on other macros, hardware, software, EPICS
    167167    channels, etc.
    168168
    169   Impact:
     169  **Impact**:
    170170    Describe the impact that the use of the macro may have. For example, list
    171171    all the changes made to other ``cdef`` macro definitions by this macro
    172172    file.
    173173
    174 File Information (top-level header):
     174**File Information (top-level header)**:
    175175  All the information about the macro file itself, like authors, license,
    176176  version, etc.
     
    386386USAGE:
    387387  The syntax for calling the macro. This should contain all possible variants
    388   of the macro call. Argument names are enclosed in bras and kets (``<>``) to
     388  of the macro call. Argument names are enclosed in angle brackets (``<>``) to
    389389  indicate that they should be replaced by actual values in the macro call.
    390390  Optional arguments are additionally enclosed in square brackets (``[]``).
    391391  The actual USAGE syntax should appear as preformatted text, and each input
    392   line should start with the ``>``-symbol to represent the SPEC command line
     392  line should start with a "``>``"-symbol to represent the SPEC command line
    393393  prompt::
    394394 
     
    415415 
    416416  Note that a number of python projects use a special kind of argument
    417   definition list which is processed by sphinx to include more information,
     417  definition list which is processed by Sphinx to include more information,
    418418  for example, the type of an argument. Other projects, however, actively
    419419  discourage its use or prefer the above style for simplicity.
     
    430430  A short example, illustrating the usage of the macro. As in the case of the
    431431  USAGE section, the syntax should appear as pre-formatted text, and each input
    432   line should start with the ``>``-symbol to represent the SPEC command line
     432  line should start with the "``>``"-symbol to represent the SPEC command line
    433433  prompt. Short explanation lines can be inserted as indented comment lines::
    434434 
     
    458458::
    459459
    460   """
    461   Concise summary line.
    462  
    463   USAGE::
    464    
    465     > my_move <motor> <position> [<sleep_time>]
    466    
    467   ARGUMENTS:
    468    
    469     Required arguments:
    470       :motor:    The motor to be moved [str].
    471       :position: The position to move the motor to [float].
    472    
    473     Optional arguments:
    474       :sleep_time: Settling time after the move has finished [float].
    475    
    476   EXAMPLE::
    477  
    478     > my_move del 23.2346 0.3
    479         # move del to 23.2346 and wait for 0.3 seconds after move finishes.
    480   NOTE:
    481     Indicate any side effects, restrictions or other usage notes here.
    482    
    483   SEE ALSO:
    484     * :spec:def:`my_move2`
    485     * :spec:global:`MOVE_FLAG`
    486    
    487   """
     460        """
     461        Concise summary line.
     462       
     463        USAGE::
     464               
     465                > my_move <motor> <position> [<sleep_time>]
     466               
     467        ARGUMENTS:
     468               
     469                Required arguments:
     470                        :motor:    The motor to be moved [str].
     471                        :position: The position to move the motor to [float].
     472               
     473                Optional arguments:
     474                        :sleep_time: Settling time after the move has finished [float].
     475               
     476        EXAMPLE::
     477       
     478                > my_move del 23.2346 0.3
     479                                # move del to 23.2346 and wait for 0.3 seconds after move finishes.
     480                               
     481        NOTE:
     482                Indicate any side effects, restrictions or other usage notes here.
     483               
     484        SEE ALSO:
     485                * :spec:def:`my_move2`
     486                * :spec:global:`MOVE_FLAG`
     487                * http://www.certif.com/spec_help/prdef.html
     488               
     489        """
    488490
    489491This results in the following:
     
    508510                > my_move del 23.2346 0.3
    509511                                # move del to 23.2346 and wait for 0.3 seconds after move finishes.
     512                               
    510513        NOTE:
    511514                Indicate any side effects, restrictions or other usage notes here.
     
    514517                * :spec:def:`my_move2`
    515518                * :spec:global:`MOVE_FLAG`
     519                * http://www.certif.com/spec_help/prdef.html
    516520   
    517  
    518 
    519 
    520 
    521 
    522 
    523 
    524 
    525 
    526 
     521
     522One-line docstrings
     523-------------------
     524
     525As mentioned previously, one-line docstrings (also called *descriptive
     526comments*) can be used to document code objects that cannot contain extended
     527docstrings.
     528
     529One-line docstrings begin with a capital letter and end with a period.
     530
     531Variables
     532~~~~~~~~~
     533Docstrings for variables provide a short description of the variable. It is
     534also recommended to specify the type of the variable in square brackets
     535(``[]``). For example::
     536
     537  global TTH     #: The scattering angle two-theta [float].
     538  local _ind     #: List index of the active reflection [int].
     539 
     540  #: Associate array with orientation reflection HKL-indices & angles [float].
     541  global ORIENTATION_REFLECTIONS
     542
     543
     544Macro definitions
     545~~~~~~~~~~~~~~~~~
     546
     547One-line docstrings for macro definitions contain a short description of the
     548purpose for the (re-)definition. For example::
     549
     550  #: Define the ccd shutter handler
     551  rdef ccdset_shutter '_ccdset_shutter'
     552
     553  #: remove ccd_getcounts from user_getcounts
     554  cdef("user_getcounts", "", "ccd_key", "delete")
     555
     556
     557Macro collection docstrings
     558----------------------------
     559
     560As of now, there is no standard yet for documenting entire collections of
     561macros, as, for example, those collected in particular directories of the SVN
     562source code repository.
     563
     564The documentation for such a collection should be in the form of normal ReST
     565files (*.rst), residing in the same directory with the macro collection. There
     566is no way of automatically including this information in the global documents
     567yet, so it will need to be added manually somewhere in the documentation tree
     568(at least in the global ``index.rst`` file or some other file that is included
     569from the global scope).
     570
Note: See TracChangeset for help on using the changeset viewer.