Changeset 1027

Timestamp:

Jul 15, 2012 11:41:05 PM (11 years ago)

Author:

jemian

Message:

refs #8, finished documenting a complete example

Location:

specdomain/trunk/src/specdomain

Files:

• doc/bugs.rst (modified) (1 diff)
• doc/conventions.rst (modified) (3 diffs)
• doc/example1.png (added)
• doc/example2.png (added)
• doc/example3.png (added)
• doc/howto-markup.rst (modified) (4 diffs)
• doc/todo.rst (modified) (1 diff)
• markup_example/conf.py (modified) (1 diff)
• markup_example/hkl_ioc.mac (modified) (2 diffs)
• markup_example/starter.py (added)
• sphinxcontrib/specmacrofileparser.py (modified) (5 diffs)

specdomain/trunk/src/specdomain/doc/bugs.rst

@@ -1 +1 @@
 .. $Id$
+
+.. _bugs:
 
 ===========

specdomain/trunk/src/specdomain/doc/conventions.rst

@@ -10 +10 @@
 These are not requirements.
 
-extended comments
+.. index:: ! extended comment
+
+extended comment
 -----------------
 
@@ -25 +27 @@
 It is assumed to be the summary.
 If the first paragraph starts with a ":", no summary text will be assumed.
+
+.. index:: ! descriptive comment
+.. _descriptive comment:
 
 descriptive comment
@@ -49 +54 @@
 
 .. spec:global:: tth    #: two-theta, the scattering angle
+
+
+.. index:: ! hidden object
 
 hidden objects

specdomain/trunk/src/specdomain/doc/howto-markup.rst

@@ -39 +39 @@
 
 Make a project directory and change directory into it.  
+(On my development system, this directory is called ``../markup_example``.)
 Copy the file above into this directory with the name *hkl_ioc.mac*.
 Then run::
@@ -83 +84 @@
         * :ref:`search`
         
-Edit *conf.py* and make this change:
+Edit *conf.py* and make these changes:
 
 ===================================================   ==============================
 change                                                directions
 ===================================================   ==============================
+``sys.path.insert(0, os.path.abspath('..'))``         *replace* line 19
 ``extensions.append( 'sphinxcontrib.specdomain' )``   insert *after* line 28
 ===================================================   ==============================
 
-The result should look like this file: :download:`../markup_example/conf.py`.
+The revised file should look like this file: :download:`../markup_example/conf.py`.
+
+Now, build the documentation by typing::
+
+    make html
+    firefox _build/html/index.html &
+
+You should expect a page that looks like this figure:
+
+.. figure:: example1.png
+    :alt: view of original hkl_ioc.mac HTML documentation
+
+    Documentation of the original **hkl_ioc.mac** file.
+
 
 Apply Markup
@@ -409 +424 @@
 Do the same thing for the *ioc_put_HKL* macro definition.
 
-
-
+Document the global variable
+----------------------------------
+
+On line 45 (in the original file), there is a global variable declaration: ``global SIOC_PV``.
+The description for this variable has been deduced from its usage in this file with EPICS.  [#]_
+It is possible to document :spec:global:`SIOC_PV` using a :ref:`descriptive comment`.
+Insert the line containing ``global SIOC_PV`` with this one::
+
+        global SIOC_PV             ;#: soft IOC PV name
+
+The semicolon is used to ensure that the spec command is finished.  It might be unnecessary.
+The descriptive comment can be used *in-line* to define the item on that line.
+
+Similarly, add another :ref:`descriptive comment` to document line 38 (original file) by inserting this
+line *before* the line that reads ``cdef("user_save_HKL","","ioc_HKL")``::
+
+        #: preload check/setting here
+        
+Here the descriptive comment appearing on one line will provide a summary
+for the item defined on the next line only.
+
+Final Results
+=================
+
+Rebuild the completed :download:`../markup_example/hkl_ioc.mac` documentation with::
+
+        make html
+
+.. note:: Don't be concerned about the warnings of
+        ``SEVERE: Duplicate ID: "cdef-user_save_HKL".``
+        These messages are only informative.  
+        This :ref:`bug <bugs>` should be resolved in a future version of ``specdomain``.
+
+After refreshing the page in the WWW browser, it should like this:
+
+.. figure:: example2.png
+    :alt: view of marked-up hkl_ioc.mac HTML documentation
+
+    Documentation of the marked-up **hkl_ioc.mac** file.
+
+and the index will look like:
+
+.. figure:: example3.png
+    :alt: index of marked-up hkl_ioc.mac HTML documentation
+
+    Index of the marked-up **hkl_ioc.mac** file.
+
+.. note::  It is :ref:`planned for the future <todo>` to provide options for sorting the output alphabetically
+        and to provide other features.
 
 -----------------
@@ -426 +488 @@
 .. [#] definition list: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
 .. [#] table: http://sphinx.pocoo.org/rest.html#tables
+.. [#] EPICS: http://www.aps.anl.gov/epics

specdomain/trunk/src/specdomain/doc/todo.rst

@@ -1 +1 @@
 .. $Id$
+
+.. _todo:
 
 =============

specdomain/trunk/src/specdomain/markup_example/conf.py

@@ -17 +17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------

specdomain/trunk/src/specdomain/markup_example/hkl_ioc.mac

@@ -49 +49 @@
 #===============================================================================
 if( unset("SIOC_PV") ) {
-#: soft IOC PV prefix
-global SIOC_PV
+global SIOC_PV             ;#: soft IOC PV name
 local foo tmp[]
 SIOC_PREFIX="4id"
@@ -70 +69 @@
     
     if(("$1" == "on")) {
-       cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")
+       cdef("user_save_HKL","ioc_put_HKL","ioc_HKL","0x20")             ;#: turn on the save to shared memory
        print "Now put HKL to softioc."
        exit
     }
     if(("$1" == "off")) {
-       cdef("user_save_HKL","","ioc_HKL","delete")
+       cdef("user_save_HKL","","ioc_HKL","delete")              ;#: turn off the save to shared memory
        print "Stop put HKL to softioc."
        exit

specdomain/trunk/src/specdomain/sphinxcontrib/specmacrofileparser.py

@@ -441 +441 @@
     #------------------------ reporting section below ----------------------------------
 
-    def ReST(self):
-        """create the ReStructured Text from what has been found"""
-        return self._simple_ReST_renderer()
-
     def _simple_ReST_renderer(self):
         """create a simple ReStructured Text rendition of the findings"""
@@ -452 +448 @@
         s = []
         for r in self.findings:
+            # TODO: need to define subsections such as these:
+            #    Summary (if present)
+            #    Documentation (if present)
+            #    Declarations
+            #    Tables
             if r['objtype'] == 'extended comment':
                 # TODO: apply rules to suppress reporting under certain circumstances
@@ -462 +463 @@
                 s.append(r['text'])
                 s.append( '' )
+#                s.append( '-'*10 )
+#                s.append( '' )
             elif r['objtype'] in ('def', 'rdef', 'cdef', ):
                 # TODO: apply rules to suppress reporting under certain circumstances
@@ -518 +521 @@
                     s.append( '' )
 
+#        s.append( '-'*10 )
+#        s.append( '' )
+
         s += _report_table('Variable Declarations (%s)' % self.filename, declarations, 
                           ('objtype', 'name', 'start_line', 'summary', ))
@@ -527 +533 @@
 
         return '\n'.join(s)
+
+    def ReST(self, style = 'simple'):
+        """create the ReStructured Text from what has been found"""
+    
+        # allow for additional renderers, selectable by options
+        renderer_dict =  {'simple': self._simple_ReST_renderer,}
+        if style not in renderer_dict:
+            raise RuntimeWarning, "%s renderer not found, using `simple`" % style
+        return renderer_dict[style]()