Changeset 1027


Ignore:
Timestamp:
Jul 15, 2012 11:41:05 PM (10 years ago)
Author:
jemian
Message:

refs #8, finished documenting a complete example

Location:
specdomain/trunk/src/specdomain
Files:
4 added
7 edited

Legend:

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

    r1017 r1027  
    11.. $Id$
     2
     3.. _bugs:
    24
    35===========
  • specdomain/trunk/src/specdomain/doc/conventions.rst

    r1007 r1027  
    1010These are not requirements.
    1111
    12 extended comments
     12.. index:: ! extended comment
     13
     14extended comment
    1315-----------------
    1416
     
    2527It is assumed to be the summary.
    2628If the first paragraph starts with a ":", no summary text will be assumed.
     29
     30.. index:: ! descriptive comment
     31.. _descriptive comment:
    2732
    2833descriptive comment
     
    4954
    5055.. spec:global:: tth    #: two-theta, the scattering angle
     56
     57
     58.. index:: ! hidden object
    5159
    5260hidden objects
  • specdomain/trunk/src/specdomain/doc/howto-markup.rst

    r1026 r1027  
    3939
    4040Make a project directory and change directory into it. 
     41(On my development system, this directory is called ``../markup_example``.)
    4142Copy the file above into this directory with the name *hkl_ioc.mac*.
    4243Then run::
     
    8384        * :ref:`search`
    8485       
    85 Edit *conf.py* and make this change:
     86Edit *conf.py* and make these changes:
    8687
    8788===================================================   ==============================
    8889change                                                directions
    8990===================================================   ==============================
     91``sys.path.insert(0, os.path.abspath('..'))``         *replace* line 19
    9092``extensions.append( 'sphinxcontrib.specdomain' )``   insert *after* line 28
    9193===================================================   ==============================
    9294
    93 The result should look like this file: :download:`../markup_example/conf.py`.
     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
    94109
    95110Apply Markup
     
    409424Do the same thing for the *ioc_put_HKL* macro definition.
    410425
    411 
    412 
     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.
    413475
    414476-----------------
     
    426488.. [#] definition list: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
    427489.. [#] table: http://sphinx.pocoo.org/rest.html#tables
     490.. [#] EPICS: http://www.aps.anl.gov/epics
  • specdomain/trunk/src/specdomain/doc/todo.rst

    r1013 r1027  
    11.. $Id$
     2
     3.. _todo:
    24
    35=============
  • specdomain/trunk/src/specdomain/markup_example/conf.py

    r1022 r1027  
    1717# add these directories to sys.path here. If the directory is relative to the
    1818# documentation root, use os.path.abspath to make it absolute, like shown here.
    19 #sys.path.insert(0, os.path.abspath('.'))
     19sys.path.insert(0, os.path.abspath('..'))
    2020
    2121# -- General configuration -----------------------------------------------------
  • specdomain/trunk/src/specdomain/markup_example/hkl_ioc.mac

    r1025 r1027  
    4949#===============================================================================
    5050if( unset("SIOC_PV") ) {
    51 #: soft IOC PV prefix
    52 global SIOC_PV
     51global SIOC_PV             ;#: soft IOC PV name
    5352local foo tmp[]
    5453SIOC_PREFIX="4id"
     
    7069   
    7170    if(("$1" == "on")) {
    72        cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")
     71       cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")             ;#: turn on the save to shared memory
    7372       print "Now put HKL to softioc."
    7473       exit
    7574    }
    7675    if(("$1" == "off")) {
    77        cdef("user_save_HKL","","ioc_HKL","delete")
     76       cdef("user_save_HKL","","ioc_HKL","delete")              ;#: turn off the save to shared memory
    7877       print "Stop put HKL to softioc."
    7978       exit
  • specdomain/trunk/src/specdomain/sphinxcontrib/specmacrofileparser.py

    r1017 r1027  
    441441    #------------------------ reporting section below ----------------------------------
    442442
    443     def ReST(self):
    444         """create the ReStructured Text from what has been found"""
    445         return self._simple_ReST_renderer()
    446 
    447443    def _simple_ReST_renderer(self):
    448444        """create a simple ReStructured Text rendition of the findings"""
     
    452448        s = []
    453449        for r in self.findings:
     450            # TODO: need to define subsections such as these:
     451            #    Summary (if present)
     452            #    Documentation (if present)
     453            #    Declarations
     454            #    Tables
    454455            if r['objtype'] == 'extended comment':
    455456                # TODO: apply rules to suppress reporting under certain circumstances
     
    462463                s.append(r['text'])
    463464                s.append( '' )
     465#                s.append( '-'*10 )
     466#                s.append( '' )
    464467            elif r['objtype'] in ('def', 'rdef', 'cdef', ):
    465468                # TODO: apply rules to suppress reporting under certain circumstances
     
    518521                    s.append( '' )
    519522
     523#        s.append( '-'*10 )
     524#        s.append( '' )
     525
    520526        s += _report_table('Variable Declarations (%s)' % self.filename, declarations,
    521527                          ('objtype', 'name', 'start_line', 'summary', ))
     
    527533
    528534        return '\n'.join(s)
     535
     536    def ReST(self, style = 'simple'):
     537        """create the ReStructured Text from what has been found"""
     538   
     539        # allow for additional renderers, selectable by options
     540        renderer_dict =  {'simple': self._simple_ReST_renderer,}
     541        if style not in renderer_dict:
     542            raise RuntimeWarning, "%s renderer not found, using `simple`" % style
     543        return renderer_dict[style]()
    529544
    530545
Note: See TracChangeset for help on using the changeset viewer.