|
1 | 1 | """ |
2 | | - tutorialformatter |
3 | | - =========================== |
4 | | -
|
5 | | - This extension provides a directive to include a source code file |
6 | | - in a document, but with certain comments from the file formatted |
7 | | - as regular document text. This allows code for a tutorial to look like: |
8 | | -
|
9 | | - /// BEGIN_TUTORIAL |
10 | | - /// This next line adds one. |
11 | | - i = i + 1; |
12 | | - /// Then we need to double it. |
13 | | - i = i * 2; |
14 | | - /// END_TUTORIAL |
15 | | -
|
16 | | - And have it formatted as |
17 | | -
|
18 | | - This next line adds one.:: |
19 | | - i = i + 1; |
20 | | -
|
21 | | - Then we need to double it.:: |
22 | | - i = i * 2; |
23 | | -
|
24 | | - The special-looking comment character sequence at the start of |
25 | | - each text line can be anything not starting or ending with |
26 | | - whitespace. tutorialformatter starts by scanning the file for the |
27 | | - string BEGIN_TUTORIAL. When it finds it, it takes all the |
28 | | - characters before BEGIN_TUTORIAL on that line, strips whitespace |
29 | | - from the left, and uses that as the text marker. So this would |
30 | | - also be fine: |
31 | | -
|
32 | | - #My Tutorial# BEGIN_TUTORIAL |
33 | | - #My Tutorial# This next line adds one. |
34 | | - i = i + 1 |
35 | | - #My Tutorial# Then we need to double it. |
36 | | - i = i * 2 |
37 | | - #My Tutorial# END_TUTORIAL |
38 | | -
|
39 | | - Sometimes the order that makes sense in the tutorial is not |
40 | | - compatible with the computer language of the code, like when a |
41 | | - callback function in C++ is defined outside of the main tutorial |
42 | | - code. To support this, you can use the tags BEGIN_SUB_TUTORIAL, |
43 | | - END_SUB_TUTORIAL, and CALL_SUB_TUTORIAL. They look like this: |
44 | | -
|
45 | | - # BEGIN_SUB_TUTORIAL callbackFunction |
46 | | - def callback(): |
47 | | - print("in callback") |
48 | | - # END_SUB_TUTORIAL |
49 | | -
|
50 | | - # BEGIN_TUTORIAL |
51 | | - # Here we call a special callback: |
52 | | - callback() |
53 | | - # which is defined as: |
54 | | - # CALL_SUB_TUTORIAL callbackFunction |
55 | | - # and then we move on to the next topic. |
56 | | -
|
57 | | - Both the BEGIN_SUB_TUTORIAL and CALL_SUB_TUTORIAL tags take an |
58 | | - argument, which is the name of the "sub-tutorial". That name does |
59 | | - not need to correspond to anything in the code. Sub-tutorials |
60 | | - cannot be nested, and they only work within a single source file |
61 | | - processed by tutorialformatter. They have no outside meaning. |
62 | | - The implementation simply slices out sub-tutorials from the input |
63 | | - lines and copies them into the output lines where-ever the |
64 | | - corresponding "call" tags are found. |
65 | | -
|
66 | | - .. moduleauthor:: Dave Hershberger <[email protected]> |
| 2 | +tutorialformatter |
| 3 | +=========================== |
| 4 | +
|
| 5 | +This extension provides a directive to include a source code file |
| 6 | +in a document, but with certain comments from the file formatted |
| 7 | +as regular document text. This allows code for a tutorial to look like: |
| 8 | +
|
| 9 | + /// BEGIN_TUTORIAL |
| 10 | + /// This next line adds one. |
| 11 | + i = i + 1; |
| 12 | + /// Then we need to double it. |
| 13 | + i = i * 2; |
| 14 | + /// END_TUTORIAL |
| 15 | +
|
| 16 | +And have it formatted as |
| 17 | +
|
| 18 | +This next line adds one.:: |
| 19 | + i = i + 1; |
| 20 | +
|
| 21 | +Then we need to double it.:: |
| 22 | + i = i * 2; |
| 23 | +
|
| 24 | +The special-looking comment character sequence at the start of |
| 25 | +each text line can be anything not starting or ending with |
| 26 | +whitespace. tutorialformatter starts by scanning the file for the |
| 27 | +string BEGIN_TUTORIAL. When it finds it, it takes all the |
| 28 | +characters before BEGIN_TUTORIAL on that line, strips whitespace |
| 29 | +from the left, and uses that as the text marker. So this would |
| 30 | +also be fine: |
| 31 | +
|
| 32 | + #My Tutorial# BEGIN_TUTORIAL |
| 33 | + #My Tutorial# This next line adds one. |
| 34 | + i = i + 1 |
| 35 | + #My Tutorial# Then we need to double it. |
| 36 | + i = i * 2 |
| 37 | + #My Tutorial# END_TUTORIAL |
| 38 | +
|
| 39 | +Sometimes the order that makes sense in the tutorial is not |
| 40 | +compatible with the computer language of the code, like when a |
| 41 | +callback function in C++ is defined outside of the main tutorial |
| 42 | +code. To support this, you can use the tags BEGIN_SUB_TUTORIAL, |
| 43 | +END_SUB_TUTORIAL, and CALL_SUB_TUTORIAL. They look like this: |
| 44 | +
|
| 45 | + # BEGIN_SUB_TUTORIAL callbackFunction |
| 46 | + def callback(): |
| 47 | + print("in callback") |
| 48 | + # END_SUB_TUTORIAL |
| 49 | +
|
| 50 | + # BEGIN_TUTORIAL |
| 51 | + # Here we call a special callback: |
| 52 | + callback() |
| 53 | + # which is defined as: |
| 54 | + # CALL_SUB_TUTORIAL callbackFunction |
| 55 | + # and then we move on to the next topic. |
| 56 | +
|
| 57 | +Both the BEGIN_SUB_TUTORIAL and CALL_SUB_TUTORIAL tags take an |
| 58 | +argument, which is the name of the "sub-tutorial". That name does |
| 59 | +not need to correspond to anything in the code. Sub-tutorials |
| 60 | +cannot be nested, and they only work within a single source file |
| 61 | +processed by tutorialformatter. They have no outside meaning. |
| 62 | +The implementation simply slices out sub-tutorials from the input |
| 63 | +lines and copies them into the output lines where-ever the |
| 64 | +corresponding "call" tags are found. |
| 65 | +
|
| 66 | +.. moduleauthor:: Dave Hershberger <[email protected]> |
67 | 67 | """ |
68 | 68 |
|
69 | 69 | # 0.1.0: First version. |
|
0 commit comments