Changeset 995


Ignore:
Timestamp:
Jul 6, 2012 4:11:36 PM (10 years ago)
Author:
jemian
Message:

refs #8, bring this up to date

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

Legend:

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

    r963 r995  
    33   You can adapt this file completely to your liking, but it should at least
    44   contain the root `toctree` directive.
     5
     6=======================================================
     7Documenting SPEC Macro Source Code with Sphinx
     8=======================================================
    59
    610.. include:: ../README
  • specdomain/trunk/src/specdomain/doc/spec.rst

    r937 r995  
    11.. $Id$
     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.
    28
    39Documenting SPEC Code
     
    511
    612.. _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
    780
    881Describing SPEC objects
     
    95168   +--------------------------------+-------------------------------+
    96169
     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
    97182
    98183.. _spec-roles:
     
    158243
    159244   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
     265Common Conventions
     266====================
     267
     268There are several conventions to help provide consistency.
     269These are not requirements.
     270
     271extended comments
     272-----------------
     273
     274Only the first extended comment in a "section" should be documented.
     275(This setting could be changed with an optional switch.)
     276
     277A "section" might be the global scope of a .mac file or a macro definition block.
     278
     279As much as possible, use the python documentation style (that is,
     280first comment is module documentation, first comment inside
     281macro definition is the macro documentation).
     282
     283hidden objects
     284----------------
     285
     286*Hidden* objects begin with at least one underline character,
     287such as ``_hidden``.  This includes macros and variables.
     288These should be optional in the documentation.
     289
     290*Anonymous* objects begin with at least two underline characters,
     291such as ``___anon``.  This includes macros and variables.
     292These should not be documented unless specifically requested and
     293only then if hidden objects are documented.
     294
     295undeclared variables
     296---------------------
     297
     298Undeclared variables (those with no formal global, local, constant,
     299or array declaration) will not be documented.  At least for now.
     300
     301parameter descriptions
     302----------------------------
     303
     304Use the same syntax as parameter declarations for Python modules. 
     305Here is an example SPEC macro with reST markup::
     306
     307        def my_comment '{
     308            '''
     309            Make a comment
     310           
     311            usage: ``my_comment "AR aligned to 15.14063 degrees"``
     312           
     313            :param str text: message to be printed
     314            '''
     315            qcomment "%s" $1
     316        }'
     317
     318which documentation looks like this:
     319
     320.. spec:def:: my_comment text
     321           
     322            Make a comment
     323           
     324            usage: ``my_comment "AR aligned to 15.14063 degrees"``
     325           
     326            :param str text: message to be printed
     327
     328------------
     329
     330.. rubric:: Footnotes
     331.. [#] *hidden* objects begin with one underline character, such as ``_hidden``
     332.. [#] *anonymous* objects begin with at least two underline characters, such as ``__anon``
     333.. [#] SPEC extended comments:  http://www.certif.com/spec_help/chg5_01.html
     334.. [#] restructured text: http://docutils.sf.net/rst.html
     335.. [#] For now, the rendition is basic.  This will be improved in a future revision.
  • specdomain/trunk/src/specdomain/doc/starter.py

    r938 r995  
    1212import sys
    1313
     14import os
     15import sphinx
     16import sys
     17
    1418
    1519def force_rebuild_all(parent = '_build'):
    1620    '''
    17     Delete the *doctrees* subdirectory.
     21    Delete the pickle file.
    1822   
    1923    :param str parent: path to *build* subdirectory (either ``build`` or ``_build``)
    2024    '''
    21     if os.path.exists(parent+'/doctrees'):
    22         garbage_list = [
    23             parent+'/doctrees/environment.pickle',
    24             #parent+'/doctrees/index.doctree',
    25             #parent+'/doctrees/test_doc.doctree',
    26         ]
    27         for item in garbage_list:
    28             if os.path.exists(item):
    29                 os.remove(item)
    30         #os.rmdir(parent+'/doctrees')
     25    pickle_file = parent+'/doctrees/environment.pickle'
     26    if os.path.exists(pickle_file):
     27        os.remove(pickle_file)
    3128
    3229
Note: See TracChangeset for help on using the changeset viewer.