source: pulse_train_doc/build/html/_sources/coaching1.txt @ 865

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

OK, good enough for now

File size: 2.4 KB
Line 
1.. $Id: coaching1.rst 863 2012-06-05 07:20:49Z jemian $
2
3===========================================
4Coaching on the use of reStructuredText
5===========================================
6
7.. note:: Web documentation available at:
8   http://subversion.xor.aps.anl.gov/bcdaext/pulse_train_doc/build/html/index.html
9
10This is a just an example of writing the documentation using sphinx. [#]_
11It is easy to edit the documentation since it is text.  You can find the built :index:`html` documentation in
12``build/html/index.html``.  To build the documentation, you need to
13be in the ``sphinxdoc`` (or whatever you name it) directory, then type::
14
15        make html
16
17It may be useful, sometimes, to completely :index:`rebuild` the documentation.
18To do that, type::
19
20        make clean
21        make html
22
23.. [#] Sphinx uses Python.  You may want to build this on an APS
24   SunOS or linux computer.  If so, you'll need to make sure
25   that the ``/APSshare/epd/{architecture_choice}/bin`` directory
26   is on your executable path.
27
28SVN export this example documentation
29---------------------------------------
30
31You can pull this example from its subversion repo and add it
32to your project by going to the desired directory
33(perhaps the TOP directory for your support) and exporting from this
34subversion repository::
35
36   svn export http://subversion.xor.aps.anl.gov/bcdaext/pulse_train_doc sphinxdoc
37
38
39
40Example 1
41---------
42
43Here is some more text.
44
45  This text is an inset.
46
47
48Example 2
49---------
50
51Tell about example 2.
52
53inline code, external code, and other literal examples
54++++++++++++++++++++++++++++++++++++++++++++++++++++++
55
56Use a different underline symbol for each section :index:`level`.  To use
57``literal text``, surround test with double backticks or end a paragraph
58with a double colon::
59
60   place a blank line
61   then indent the text to be made to look like a program
62
63It is possible to include all or even part of code files in
64any accessible directory.
65
66.. code-block:: guess
67   :linenos:
68
69   # this is some example C code
70   for (i=10; i; i--)  i*i;
71
72.. literalinclude:: index.rst
73    :linenos:
74    :language: guess
75
76.. note:: More :index:`!help` is available from the sphinx
77   link (http://sphinx.pocoo.org/) at the bottom of this web page.
78
79UNIX Makefile
80+++++++++++++++
81
82.. literalinclude:: ../Makefile
83    :linenos:
84    :language: guess
85
86Indices and tables
87==================
88
89* :ref:`genindex`
90* :ref:`search`
91
Note: See TracBrowser for help on using the repository browser.