source: specdomain/trunk/src/specdomain/doc/howto-markup.rst @ 1021

Last change on this file since 1021 was 1021, checked in by jemian, 10 years ago

work-in-progress

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 1.2 KB
Line 
1.. $Id: howto-markup.rst 1021 2012-07-15 22:44:17Z jemian $
2
3==========================================================
4How to Markup a SPEC Macro File
5==========================================================
6
7#. start with SPEC macro file that is not marked up
8#. create a Sphinx documentation project
9#. apply markup
10#. test
11
12Basic SPEC Macro file
13==============================
14
15This example is a SPEC macro file from the APS subversion repository:
16https://subversion.xor.aps.anl.gov/spec/macros/trunk/common/hkl_ioc.mac
17because it is simple, brief, does not contain references to other
18macro files, provides its documentation in SPEC comments, and has not been
19marked up previously for documentation with Sphinx.  Here is the file
20``hkl_ioc.mac`` in its entirety.
21
22.. literalinclude:: ex_markup/hkl_ioc.mac
23    :tab-width: 4
24    :linenos:
25    :language: guess
26
27
28
29Create a Sphinx Project
30==============================
31
32.. tip:: Use an *in-source* configuration
33.. make a reference to in-source
34
35--tba--
36
37Apply Markup
38==============================
39
40#. normal SPEC comments
41#. extended comments (docstrings)
42   #. global docstring
43   #. macro docstring
44   #. others are ignored by Sphinx
45#. descriptive comments
46
47--tba--
48
49Test
50-----------
51
52--tba--
Note: See TracBrowser for help on using the repository browser.