Changeset 919

Timestamp:

Jun 12, 2012 5:10:09 PM (10 years ago)

Author:

jemian

Message:

refs #8, rest for the night

Location:

specdomain/src/specdomain

Files:

• doc/changes.rst (added)
• doc/index.rst (modified) (2 diffs)
• doc/license.rst (added)
• doc/objectives.rst (added)
• doc/starter.py (added)
• sphinxcontrib/specdomain.py (modified) (1 diff)
• test/conf.py (modified) (2 props)
• test/index.rst (modified) (1 diff)
• test/starter.py (added)
• test/test_doc.rst (modified) (2 diffs)

specdomain/src/specdomain/doc/index.rst

@@ -11 +11 @@
    :maxdepth: 2
 
+   objectives
    reference
+   changes
+   license
 
 * :ref:`genindex`
@@ -20 +23 @@
 
 .. include:: ../AUTHORS
-
-ChangeLog
-=========
-
-.. include:: ../CHANGES
-
-
-License
-=======
-
-.. literalinclude:: ../LICENSE
-    :linenos:

specdomain/src/specdomain/sphinxcontrib/specdomain.py

@@ -392 +392 @@
     label = 'SPEC'
     object_types = {
-        'function': ObjType(l_('function'), 'func'),
-        'macro':    ObjType(l_('macro'),    'macro'),
-        'global':   ObjType(l_('global'),   'global'),
-        'record':   ObjType(l_('record'),   'record'),
-        'module':   ObjType(l_('module'),   'mod'),
-        'variable': ObjType(l_('variable'), 'var'),
+        'def':      ObjType(l_('def'),      'def'),
+        'rdef':     ObjType(l_('rdef'),     'rdef'),
+        'cdef':     ObjType(l_('cdef'),     'cdef'),
+        #'record':   ObjType(l_('record'),   'record'),
+        #'module':   ObjType(l_('module'),   'mod'),
+        #'variable': ObjType(l_('variable'), 'var'),
     }
     directives = {
-        'function':      SpecObject,
-        'macro':         SpecObject,
-        'record':        SpecObject,
-        'module':        SpecModule,
-        'variable':      SpecVariable,
-        'global':        SpecVariable,
-        'currentmodule': SpecCurrentModule,
+        'def':      SpecObject,
+        'rdef':     SpecObject,
+        'cdef':     SpecObject,
+        #'module':        SpecModule,
+        #'variable':      SpecVariable,
+        #'global':        SpecVariable,
+        #'currentmodule': SpecCurrentModule,
     }
     roles = {
-        'func' :  SpecXRefRole(),
-        'macro':  SpecXRefRole(),
-        'global': SpecXRefRole(),
-        'record': SpecXRefRole(),
-        'mod':    SpecXRefRole(),
+        'def' :     SpecXRefRole(),
+        'rdef':     SpecXRefRole(),
+        'cdef':     SpecXRefRole(),
+        #'record': SpecXRefRole(),
+        #'mod':    SpecXRefRole(),
     }
     initial_data = {

specdomain/src/specdomain/test/index.rst

@@ -18 +18 @@
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
+*documentation built*: 
+|today|

specdomain/src/specdomain/test/test_doc.rst

@@ +1 @@
+.. $Id$
+
 ===============
 Acceptance Test
@@ -5 +7 @@
 If all links are valid, test is done successfully.
 
-Global (spec module's contents)
-===============================
 
-.. spec:function:: function_out_of_module
+Directives
+==========
 
-.. spec:module:: test_module
+A *directive* can be used to define the anchor point of a reference.
+Index entries will point back to the *directive*.  If the item 
+defined in the directive is not obtained from the source code, 
+then define it here, like these.  All of these directives should 
+have entries in an Index.
 
-.. define various tests
+SPEC Macros
+^^^^^^^^^^^
+
+.. spec:def:: example_defined_macro [arg1 [arg2 [...]]]
+
+   :param arg1: anything
+   :type  arg1: str
+   :param arg2: another thing
+
+.. spec:rdef:: example_runtime_defined_macro content
+
+   :param content: SPEC code (single or multi-line but typically a single macro)
+   :type  content: str
+
+.. spec:cdef:: example_chained_macro(identifier, content, placement)
+
+   :param identifier: one-word name for this macro chain
+   :type  identifier: str
+   :param content: SPEC code to be inserted (typically a single macro)
+   :type  content: str
+   :param placement: see the manual
+   :type  placement: str
+
+SPEC Variables
+^^^^^^^^^^^^^^
+
+* global variable declaration: 
+* local variable declaration: 
+* array variable declaration: 
+
+Python example
+^^^^^^^^^^^^^^
+
+.. py:function:: the_time(t = None)
+
+   :param t: time_t object or None (defaults to ``now()``)
+   :type  t: str
+
+
+Roles
+=====
+
+A *role* refers to a *directive* (makes a link to a *directive* defined elsewhere).
+Each of these items should produce a valid link.
+
+SPEC Macros
+^^^^^^^^^^^
+
+* macro definition: :spec:def:`example_defined_macro`
+* runtime-defined macro definition: :spec:rdef:`example_runtime_defined_macro`
+* chained macro definition: :spec:cdef:`example_chained_macro`
+
+SPEC Variables
+^^^^^^^^^^^^^^
+
+* global variable declaration: 
+* local variable declaration: 
+* array variable declaration: 
+
+Python example
+^^^^^^^^^^^^^^
+
+See the python method :py:func:`the_time()` (defined above)