Changeset 1028


Ignore:
Timestamp:
Jul 16, 2012 1:06:58 AM (11 years ago)
Author:
jemian
Message:

refs #8: finish the documentation

Location:
specdomain/trunk/src/specdomain
Files:
5 added
8 edited
2 moved

Legend:

Unmodified
Added
Removed

  • specdomain/trunk/src/specdomain/CHANGES

    r1007 r1028  
    33This file describes user-visible changes between the extension versions.
    44
    5 Version 1.0 (2012-07-13)
     5Version 1.0 (2012-07-16)
    66------------------------
    77

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

    r1027 r1028  
    1111* fix the signature recognition for roles
    1212* fix the signature handling for roles and directives
     13* the out-of-source example PNG shows a Python project, should be a SPEC project

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

    r1027 r1028  
    11.. $Id$
     2
     3.. index::  ! SPEC conventions
     4        see: conventions; SPEC conventions
    25
    36====================================================================
    … …  
    69
    710There are several conventions
    8 for documenting SPEC macro source Codefiles
     11for documenting SPEC macro source code files
    912to help provide consistency.
    1013These are not requirements.
    1114
    12 .. index:: ! extended comment
     15.. index::
     16        pair:   SPEC conventions; extended comments
     17
     18.. _convention for extended comment:
    1319
    1420extended comment
    … …  
    1824(This setting could be changed with an optional switch.)
    1925
    20 A "section" might be the global scope of a .mac file or a macro definition block.
     26A *section* might be the global scope of a .mac file or a macro definition block.
    2127
    2228As much as possible, use the python documentation style (that is,
    … …  
    2834If the first paragraph starts with a ":", no summary text will be assumed.
    2935
    30 .. index:: ! descriptive comment
     36
     37
     38.. index:: ! descriptive comments
     39        pair:   SPEC conventions; descriptive comments
     40
    3141.. _descriptive comment:
    3242
    … …  
    5666
    5767
    58 .. index:: ! hidden object
     68
     69
     70.. index:: ! hidden objects
     71        pair:   SPEC conventions; hidden objects
    5972
    6073hidden objects

  • specdomain/trunk/src/specdomain/doc/howto-build.rst

    r1013 r1028  
    66====================================================================
    77
    8 --tba--
    9 
    10 ::
     8Briefly::
    119
    1210        make html

  • specdomain/trunk/src/specdomain/doc/howto-configure.rst

    r1022 r1028  
    2828files are in **the same directory** as the SPEC macro files.
    2929
    30 Here is a graphical example:  --tba--
     30Here is a graphical example:
     31
     32.. figure:: in-source.png
     33    :alt: example directory of an in-source configuration
     34
     35    Example directory of an in-source configuration
    3136
    3237.. index:: ! out-of-source configuration
    … …  
    3843files are in **a separate directory** from the SPEC macro files.
    3944
    40 Here is a graphical example:  --tba--
     45Here is a graphical example: [#]_
     46
     47.. figure:: out-of-source1.png
     48    :alt: example build directory of an out-of-source configuration
     49
     50    Example build directory of an out-of-source configuration
     51
     52The source files are located in the *source* directory (child of the build directory):
     53
     54.. figure:: out-of-source2.png
     55    :alt: example *source* directory of an out-of-source configuration
     56
     57    Example *source* directory of an out-of-source configuration
     58
     59
     60.. caution::  FIXME: these are Python files and project directories.
     61        The figure *should* be shown with SPEC macro files out-of-source.
     62
     63
    4164
    4265Create the Sphinx documentation tree
    … …  
    5477        cd /tmp/sandbox
    5578
    56 Create a Sphinx configuration in this directory by running ``sphinx-quickstart``:
     79.. index:: sphinx-quickstart
     80
     81Create a Sphinx configuration in this directory by running::
     82
     83        sphinx-quickstart
     84
     85Here's the full session:
    5786
    5887.. code-block:: text
    … …  
    134163        jemian@como-ubuntu64:/tmp/sandbox$ 
    135164
     165In case you missed them, these are the non-default answers supplied:
     166
     167=========================================================================================  ===============
     168prompt                                                                                     response
     169=========================================================================================  ===============
     170``> Project name:``                                                                        *sandbox*
     171``> Author name(s):``                                                                      *sandy*
     172``> Project version:``                                                                     *test*
     173``> autodoc: automatically insert docstrings from modules (y/N) [n]:``                     *y*
     174``> viewcode: include links to the source code of documented Python objects (y/N) [n]:``   *y*
     175=========================================================================================  ===============
     176
    136177
    137178Configure: Changes to ``conf.py``
    … …  
    153194
    154195        html_theme = 'sphinxdoc'
     196
     197
     198----------------------------------
     199
     200.. rubric:: Footnotes
     201
     202.. [#] The green check boxes correspond to the status of each item in the version control system.

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

    r1027 r1028  
    5151prompt                                                                                    response
    5252========================================================================================  ================================
    53 ``> Project name:``                                                                       **example**
    54 ``> Author name(s):``                                                                     **SPEC Macro Writer**
    55 ``> Project version:``                                                                    **1**
    56 ``> autodoc: automatically insert docstrings from modules (y/N) [n]:``                    **y**
    57 ``> viewcode: include links to the source code of documented Python objects (y/N) [n]:``  **y**
     53``> Project name:``                                                                       *example*
     54``> Author name(s):``                                                                     *SPEC Macro Writer*
     55``> Project version:``                                                                    *1*
     56``> autodoc: automatically insert docstrings from modules (y/N) [n]:``                    *y*
     57``> viewcode: include links to the source code of documented Python objects (y/N) [n]:``  *y*
    5858========================================================================================  ================================
    5959
    … …  
    205205Note that the two colons indicate literal text follows. 
    206206Both the blank line after the colons and the final blank line are required to avoid warnings.
    207 And, the entire comment must be indented at least one column to the right of the two colons.
     207And, the entire comment *must be indented* at least one column to the right of the two colons.
    208208
    209209reST markup
    … …  
    240240This markup does not look too complicated until we reach the *Modification history*
    241241starting at line 23.  The content here might be coded as either literal text (above)
    242 or a reST table.  Since the table is easy *and* CVS is no longer used, we'll
    243 format it as a table.
     242or a reST table.  Since the table is easy *and* CVS is no longer used to build the
     243revision history, we'll format it as a table.
    244244
    245245Consider this SPEC comment:
    … …  
    354354User macros
    355355        ioc_HKL -> to turn on/off the feature of putting HKL to shared
    356                            memory.
     356        memory.
    357357
    358358Internal macros

  • specdomain/trunk/src/specdomain/doc/index.rst

    r1007 r1028  
    1717
    1818   howto
     19   examples
    1920   conventions
    2021   spec
    21    example
    22    bpm
    23    aalength
    2422
    2523Other matters

  • specdomain/trunk/src/specdomain/doc/simple.mac

    r1027 r1028  
    4848def CheckSaveToFile '{
    4949  """
     50  Helps prevent user from writing data to */dev/null* by accident.
     51 
    5052  This macro will run when SPEC starts and checks
    51   if the output is directed into a file or might be ignored.
     53  if the output is directed into a file or might be ignored (written to */dev/null*).
    5254  It runs :spec:def:`newsample` if the output might be ignored.
    5355  """

  • specdomain/trunk/src/specdomain/doc/simple.rst

    r1027 r1028  
    22
    33====================================================================
    4 Example SPEC Macro Source Code File Documentation
     4Simple Example to Document a SPEC Macro File
    55====================================================================
    66
    77This example demonstrates how a file with simple reST markup will be documented.::
    88
    9         .. autospecmacro:: example.mac
     9        .. autospecmacro:: simple.mac
    1010
    11 .. autospecmacro:: example.mac
     11.. autospecmacro:: simple.mac

  • specdomain/trunk/src/specdomain/doc/spec.rst

    r1007 r1028  
    6969--------------------------------
    7070
     71.. sidebar:: Do not use the single-quote character to mark an extended comment.
     72
     73        In the Python language, a triple-quoted string is known as a docstring.
     74        But, **unlike Python**, SPEC does not recognize single quotes
     75        to mark extended comments.  Only use the double quote character for SPEC files.
     76
    7177Since 2002, SPEC has provided an *extended comment* block. [#]_
    7278Such a block begins and ends
    … …  
    7682
    7783Here, the extended comment block should be formatted according to the conventions of
    78 restructured text [#]_.
     84restructured text [#]_.  There is also a
     85:ref:`recommended convention <convention for extended comment>`
     86for using extended comments in SPEC macro files.
     87
    7988
    8089
Note: See TracChangeset for help on using the changeset viewer.