codnar 0.1.66 → 0.1.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/ChangeLog +1 -0
- data/README.rdoc +2 -1
- data/Rakefile +4 -0
- data/codnar.html +376 -9
- data/doc/dataflow.dot +16 -0
- data/doc/system.markdown +28 -0
- data/lib/codnar.rb +1 -0
- data/lib/codnar/formatter.rb +3 -2
- data/lib/codnar/graphviz.rb +42 -0
- data/lib/codnar/markdown.rb +1 -1
- data/lib/codnar/split_configurations.rb +11 -3
- data/lib/codnar/version.rb +1 -1
- data/test/graphviz_diagrams.rb +53 -0
- data/test/split_documentation.rb +1 -1
- metadata +9 -5
data/ChangeLog
CHANGED
data/README.rdoc
CHANGED
@@ -14,7 +14,8 @@ into a narrative that describes the overall system.
|
|
14
14
|
|
15
15
|
A simple <tt>gem install codnar</tt> should do the trick, assuming you have
|
16
16
|
Ruby gems set up. If you want to use the VIM-based syntax highlighting, you
|
17
|
-
also need to install <tt>gvim</tt>.
|
17
|
+
also need to install <tt>gvim</tt>. Similarly, you need to install
|
18
|
+
<tt>GraphViz</tt> to be able to embed SVG diagrams in your HTML.
|
18
19
|
|
19
20
|
=== Usage
|
20
21
|
|
data/Rakefile
CHANGED
@@ -15,7 +15,11 @@ Olag::Rake::CODNAR_CONFIGURATIONS.unshift([
|
|
15
15
|
"classify_source_code:ruby",
|
16
16
|
"format_code_gvim_css:ruby",
|
17
17
|
"classify_nested_code:ruby:html",
|
18
|
+
"classify_nested_code:ruby:dot",
|
19
|
+
"classify_nested_code:ruby:svg",
|
18
20
|
"format_code_gvim_css:html",
|
21
|
+
"format_code_gvim_css:dot",
|
22
|
+
"format_code_gvim_css:svg",
|
19
23
|
"classify_shell_comments",
|
20
24
|
"format_rdoc_comments",
|
21
25
|
], [
|
data/codnar.html
CHANGED
@@ -394,7 +394,8 @@ weaves them back into a narrative that describes the overall system.
|
|
394
394
|
<p>
|
395
395
|
A simple <tt>gem install codnar</tt> should do the trick, assuming you have
|
396
396
|
Ruby gems set up. If you want to use the VIM-based syntax highlighting, you
|
397
|
-
also need to install <tt>gvim</tt>.
|
397
|
+
also need to install <tt>gvim</tt>. Similarly, you need to install
|
398
|
+
<tt>GraphViz</tt> to be able to embed SVG diagrams in your HTML.
|
398
399
|
</p>
|
399
400
|
<h3>Usage</h3>
|
400
401
|
<p>
|
@@ -686,7 +687,7 @@ number of Git commits by running <tt>rake version</tt>.
|
|
686
687
|
</tr>
|
687
688
|
</table>
|
688
689
|
<pre class='ruby code syntax'>
|
689
|
-
<span class="Type">VERSION</span> = <span class="Special">"</span><span class="Constant">0.1.
|
690
|
+
<span class="Type">VERSION</span> = <span class="Special">"</span><span class="Constant">0.1.67</span><span class="Special">"</span>
|
690
691
|
|
691
692
|
end
|
692
693
|
</pre>
|
@@ -704,6 +705,100 @@ for Rake integration.
|
|
704
705
|
</p>
|
705
706
|
</div>
|
706
707
|
<div class='markdown doc markup'>
|
708
|
+
<h2>Data Flow</h2>
|
709
|
+
<p>
|
710
|
+
Here is a diagram showing the overall data flow in a system documented with
|
711
|
+
Codnar:
|
712
|
+
</p>
|
713
|
+
<p>
|
714
|
+
<div class="plain chunk">
|
715
|
+
<a name="doc-dataflow-dot"/>
|
716
|
+
<div class='graphviz doc markup'>
|
717
|
+
<svg width="512pt" height="98pt"
|
718
|
+
viewBox="0.00 0.00 512.00 98.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
719
|
+
<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 94)">
|
720
|
+
<title>Codnar Dataflow</title>
|
721
|
+
<polygon fill="white" stroke="white" points="-4,5 -4,-94 509,-94 509,5 -4,5"/>
|
722
|
+
<!-- Documentation -->
|
723
|
+
<g id="node1" class="node"><title>Documentation</title>
|
724
|
+
<polygon fill="none" stroke="black" points="101,-90 1,-90 1,-54 101,-54 101,-90"/>
|
725
|
+
<text text-anchor="middle" x="51" y="-67.4" font-family="Times New Roman,serif" font-size="14.00">Documentation</text>
|
726
|
+
</g>
|
727
|
+
<!-- Split -->
|
728
|
+
<g id="node3" class="node"><title>Split</title>
|
729
|
+
<ellipse fill="none" stroke="black" cx="169" cy="-72" rx="28.1745" ry="18"/>
|
730
|
+
<text text-anchor="middle" x="169" y="-67.4" font-family="Times New Roman,serif" font-size="14.00">Split</text>
|
731
|
+
</g>
|
732
|
+
<!-- Documentation->Split -->
|
733
|
+
<g id="edge2" class="edge"><title>Documentation->Split</title>
|
734
|
+
<path fill="none" stroke="black" d="M101.727,-72C111.44,-72 121.457,-72 130.699,-72"/>
|
735
|
+
<polygon fill="black" stroke="black" points="130.745,-75.5001 140.745,-72 130.745,-68.5001 130.745,-75.5001"/>
|
736
|
+
</g>
|
737
|
+
<!-- Sources -->
|
738
|
+
<g id="node2" class="node"><title>Sources</title>
|
739
|
+
<polygon fill="none" stroke="black" points="82,-36 20,-36 20,-1.06581e-014 82,-0 82,-36"/>
|
740
|
+
<text text-anchor="middle" x="51" y="-13.4" font-family="Times New Roman,serif" font-size="14.00">Sources</text>
|
741
|
+
</g>
|
742
|
+
<!-- Sources->Split -->
|
743
|
+
<g id="edge4" class="edge"><title>Sources->Split</title>
|
744
|
+
<path fill="none" stroke="black" d="M82.0031,-32.1879C98.785,-39.8677 119.501,-49.3478 136.507,-57.1305"/>
|
745
|
+
<polygon fill="black" stroke="black" points="135.485,-60.5114 146.034,-61.4902 138.397,-54.1463 135.485,-60.5114"/>
|
746
|
+
</g>
|
747
|
+
<!-- Build -->
|
748
|
+
<g id="node7" class="node"><title>Build</title>
|
749
|
+
<ellipse fill="none" stroke="black" cx="169" cy="-18" rx="30.8577" ry="18"/>
|
750
|
+
<text text-anchor="middle" x="169" y="-13.4" font-family="Times New Roman,serif" font-size="14.00">Build</text>
|
751
|
+
</g>
|
752
|
+
<!-- Sources->Build -->
|
753
|
+
<g id="edge9" class="edge"><title>Sources->Build</title>
|
754
|
+
<path fill="none" stroke="black" d="M82.0031,-18C95.9842,-18 112.696,-18 127.718,-18"/>
|
755
|
+
<polygon fill="black" stroke="black" points="127.794,-21.5001 137.794,-18 127.794,-14.5001 127.794,-21.5001"/>
|
756
|
+
</g>
|
757
|
+
<!-- Chunks -->
|
758
|
+
<g id="node4" class="node"><title>Chunks</title>
|
759
|
+
<polygon fill="none" stroke="black" points="298,-90 240,-90 240,-54 298,-54 298,-90"/>
|
760
|
+
<text text-anchor="middle" x="269" y="-67.4" font-family="Times New Roman,serif" font-size="14.00">Chunks</text>
|
761
|
+
</g>
|
762
|
+
<!-- Split->Chunks -->
|
763
|
+
<g id="edge5" class="edge"><title>Split->Chunks</title>
|
764
|
+
<path fill="none" stroke="black" d="M197.122,-72C207.103,-72 218.533,-72 229.298,-72"/>
|
765
|
+
<polygon fill="black" stroke="black" points="229.346,-75.5001 239.346,-72 229.346,-68.5001 229.346,-75.5001"/>
|
766
|
+
</g>
|
767
|
+
<!-- Weave -->
|
768
|
+
<g id="node5" class="node"><title>Weave</title>
|
769
|
+
<ellipse fill="none" stroke="black" cx="375" cy="-72" rx="36.8951" ry="18"/>
|
770
|
+
<text text-anchor="middle" x="375" y="-67.4" font-family="Times New Roman,serif" font-size="14.00">Weave</text>
|
771
|
+
</g>
|
772
|
+
<!-- Chunks->Weave -->
|
773
|
+
<g id="edge6" class="edge"><title>Chunks->Weave</title>
|
774
|
+
<path fill="none" stroke="black" d="M298.527,-72C307.529,-72 317.663,-72 327.539,-72"/>
|
775
|
+
<polygon fill="black" stroke="black" points="327.677,-75.5001 337.677,-72 327.677,-68.5001 327.677,-75.5001"/>
|
776
|
+
</g>
|
777
|
+
<!-- HTML -->
|
778
|
+
<g id="node6" class="node"><title>HTML</title>
|
779
|
+
<polygon fill="none" stroke="black" points="504,-90 448,-90 448,-54 504,-54 504,-90"/>
|
780
|
+
<text text-anchor="middle" x="476" y="-67.4" font-family="Times New Roman,serif" font-size="14.00">HTML</text>
|
781
|
+
</g>
|
782
|
+
<!-- Weave->HTML -->
|
783
|
+
<g id="edge7" class="edge"><title>Weave->HTML</title>
|
784
|
+
<path fill="none" stroke="black" d="M412.035,-72C420.348,-72 429.186,-72 437.555,-72"/>
|
785
|
+
<polygon fill="black" stroke="black" points="437.83,-75.5001 447.83,-72 437.83,-68.5001 437.83,-75.5001"/>
|
786
|
+
</g>
|
787
|
+
<!-- Program -->
|
788
|
+
<g id="node8" class="node"><title>Program</title>
|
789
|
+
<polygon fill="none" stroke="black" points="301,-36 237,-36 237,-1.06581e-014 301,-0 301,-36"/>
|
790
|
+
<text text-anchor="middle" x="269" y="-13.4" font-family="Times New Roman,serif" font-size="14.00">Program</text>
|
791
|
+
</g>
|
792
|
+
<!-- Build->Program -->
|
793
|
+
<g id="edge10" class="edge"><title>Build->Program</title>
|
794
|
+
<path fill="none" stroke="black" d="M200.092,-18C208.334,-18 217.38,-18 226.128,-18"/>
|
795
|
+
<polygon fill="black" stroke="black" points="226.196,-21.5001 236.196,-18 226.196,-14.5001 226.196,-21.5001"/>
|
796
|
+
</g>
|
797
|
+
</g>
|
798
|
+
</svg>
|
799
|
+
</div>
|
800
|
+
</div>
|
801
|
+
</p>
|
707
802
|
<h2>Splitting files into chunks</h2>
|
708
803
|
<p>
|
709
804
|
Codnar makes the reasonable assumption that each source file can be effectively
|
@@ -2779,10 +2874,11 @@ Convert a sequence of marked-up classified lines to (unindented) HTML
|
|
2779
2874
|
</tr>
|
2780
2875
|
</table>
|
2781
2876
|
<pre class='ruby code syntax'>
|
2782
|
-
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">markup_lines_to_html</span>(lines, klass)
|
2877
|
+
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">markup_lines_to_html</span>(lines, klass, css_class = <span class="Constant">nil</span>)
|
2783
2878
|
implementation = <span class="Type">String</span> === klass ? <span class="Type">Kernel</span>.const_get(klass) : klass
|
2879
|
+
css_class ||= implementation.to_s.downcase.gsub(<span class="Special">"</span><span class="Constant">::</span><span class="Special">"</span>, <span class="Special">"</span><span class="Constant">-</span><span class="Special">"</span>)
|
2784
2880
|
<span class="Statement">return</span> <span class="Type">Formatter</span>.merge_lines(lines, <span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span>, <span class="Special">""</span>) <span class="Statement">do</span> |<span class="Identifier">payload</span>|
|
2785
|
-
( <span class="Special">"</span><span class="Constant"><div class='</span><span class="Special">#{</span>
|
2881
|
+
( <span class="Special">"</span><span class="Constant"><div class='</span><span class="Special">#{</span>css_class<span class="Special">}</span><span class="Constant"> </span><span class="Special">#{</span>lines[<span class="Constant">0</span>].kind<span class="Special">}</span><span class="Constant"> markup'></span><span class="Special">\n</span><span class="Special">"</span> \
|
2786
2882
|
+ implementation.to_html(payload) \
|
2787
2883
|
+ <span class="Special">"</span><span class="Constant"></div></span><span class="Special">"</span> )
|
2788
2884
|
<span class="Statement">end</span>
|
@@ -3059,7 +3155,7 @@ above.
|
|
3059
3155
|
<p>
|
3060
3156
|
Expand “[[chunk|template]]” to HTML embed tags. Use identifiers instead
|
3061
3157
|
of names in the <tt>src</tt> field for safety, unless the template is a
|
3062
|
-
magical file template, in which case we must preserve the file path
|
3158
|
+
magical file template, in which case we must preserve the file path.
|
3063
3159
|
</p>
|
3064
3160
|
</div>
|
3065
3161
|
</td>
|
@@ -3176,6 +3272,249 @@ and eliminates the ugly additional vertical space in the final HTML.
|
|
3176
3272
|
</div>
|
3177
3273
|
</div>
|
3178
3274
|
</p>
|
3275
|
+
<h4>Generating diagrams using GraphViz</h4>
|
3276
|
+
<p>
|
3277
|
+
If you have <code>graphviz</code> installed, it is possible to use it to generate SVG
|
3278
|
+
diagrams that can be embedded directly into the HTML. This is implemented as an
|
3279
|
+
additional formatter; in principle, you this allows embeding the GraphViz
|
3280
|
+
directives directly in the code, but in practice people prefer keeping the
|
3281
|
+
diagrams as separate files.
|
3282
|
+
</p>
|
3283
|
+
<p>
|
3284
|
+
We pre-process the GraphViz directives using the <code>m4</code> macro processor. This
|
3285
|
+
allows dramatically reducing the amount of repeated boilerplate in the diagram
|
3286
|
+
definitions, by defining macros for node and edge styles and, if desired, more
|
3287
|
+
advanced techniques.
|
3288
|
+
</p>
|
3289
|
+
<p>
|
3290
|
+
Here is a simple test that demonstrates generating SVG from a GraphViz diagram:
|
3291
|
+
</p>
|
3292
|
+
<p>
|
3293
|
+
<div class="named_with_containers chunk">
|
3294
|
+
<div class="chunk name">
|
3295
|
+
<a name="test-graphviz-diagrams-rb">
|
3296
|
+
<span>test/graphviz_diagrams.rb</span>
|
3297
|
+
</a>
|
3298
|
+
</div>
|
3299
|
+
<div class="chunk html">
|
3300
|
+
<pre class='ruby code syntax'>
|
3301
|
+
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar</span><span class="Special">"</span>
|
3302
|
+
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">test/spec</span><span class="Special">"</span>
|
3303
|
+
|
3304
|
+
</pre>
|
3305
|
+
<table class='layout'>
|
3306
|
+
<tr>
|
3307
|
+
<td class='indentation'>
|
3308
|
+
<pre></pre>
|
3309
|
+
</td>
|
3310
|
+
<td class='html'>
|
3311
|
+
<div class='rdoc comment markup'>
|
3312
|
+
<p>
|
3313
|
+
Test highlighting syntax using GVim.
|
3314
|
+
</p>
|
3315
|
+
</div>
|
3316
|
+
</td>
|
3317
|
+
</tr>
|
3318
|
+
</table>
|
3319
|
+
<pre class='ruby code syntax'>
|
3320
|
+
<span class="PreProc">class</span> <span class="Type">TestGraphVizDiagrams</span> < <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
|
3321
|
+
|
3322
|
+
<span class="Type">MINIMAL_DIAGRAM_SVG</span> = <<-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( svg</span>
|
3323
|
+
</pre>
|
3324
|
+
<pre class='svg code syntax'>
|
3325
|
+
<span class="Identifier"><</span><span class="Identifier">svg</span><span class="Identifier"> </span><span class="Type">width</span>=<span class="Constant">"62pt"</span><span class="Identifier"> </span><span class="Type">height</span>=<span class="Constant">"116pt"</span>
|
3326
|
+
<span class="Identifier"> </span><span class="Type">viewBox</span>=<span class="Constant">"0.00 0.00 62.00 116.00"</span><span class="Identifier"> </span><span class="Type">xmlns</span>=<span class="Constant">"<a href="http://www.w3.org/2000/svg">http://www.w3.org/2000/svg</a>"</span><span class="Identifier"> </span><span class="Type">xmlns</span><span class="Comment">:</span><span class="Type">xlink</span>=<span class="Constant">"<a href="http://www.w3.org/1999/xlink">http://www.w3.org/1999/xlink</a>"</span><span class="Identifier">></span>
|
3327
|
+
<span class="Identifier"><</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">"graph1"</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">"graph"</span><span class="Identifier"> </span><span class="Type">transform</span>=<span class="Constant">"scale(1 1) rotate(0) translate(4 112)"</span><span class="Identifier">></span>
|
3328
|
+
<span class="Identifier"><</span><span class="Identifier">title</span><span class="Identifier">></span>_anonymous_0<span class="Identifier"></title></span>
|
3329
|
+
<span class="Identifier"><</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">"white"</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">"white"</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">"-4,5 -4,-112 59,-112 59,5 -4,5"</span><span class="Identifier">/></span>
|
3330
|
+
<span class="Comment"><!</span><span class="Comment">-- A --</span><span class="Comment">></span>
|
3331
|
+
<span class="Identifier"><</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">"node1"</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">"node"</span><span class="Identifier">><</span><span class="Identifier">title</span><span class="Identifier">></span>A<span class="Identifier"></title></span>
|
3332
|
+
<span class="Identifier"><</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">"none"</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">"black"</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">"-90"</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">"18"</span><span class="Identifier">/></span>
|
3333
|
+
<span class="Identifier"><</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">"middle"</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">"-85.4"</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">"Times New Roman,serif"</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">"14.00"</span><span class="Identifier">></span>A<span class="Identifier"></text></span>
|
3334
|
+
<span class="Identifier"></g></span>
|
3335
|
+
<span class="Comment"><!</span><span class="Comment">-- B --</span><span class="Comment">></span>
|
3336
|
+
<span class="Identifier"><</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">"node3"</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">"node"</span><span class="Identifier">><</span><span class="Identifier">title</span><span class="Identifier">></span>B<span class="Identifier"></title></span>
|
3337
|
+
<span class="Identifier"><</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">"none"</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">"black"</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">"-18"</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">"18"</span><span class="Identifier">/></span>
|
3338
|
+
<span class="Identifier"><</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">"middle"</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">"27"</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">"-13.4"</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">"Times New Roman,serif"</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">"14.00"</span><span class="Identifier">></span>B<span class="Identifier"></text></span>
|
3339
|
+
<span class="Identifier"></g></span>
|
3340
|
+
<span class="Comment"><!</span><span class="Comment">-- A&#45;&gt;B --</span><span class="Comment">></span>
|
3341
|
+
<span class="Identifier"><</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">"edge2"</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">"edge"</span><span class="Identifier">><</span><span class="Identifier">title</span><span class="Identifier">></span>A<span class="Type">&</span><span class="Statement">#45</span><span class="Type">;&</span><span class="Statement">gt</span><span class="Type">;</span>B<span class="Identifier"></title></span>
|
3342
|
+
<span class="Identifier"><</span><span class="Identifier">path</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">"none"</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">"black"</span><span class="Identifier"> </span><span class="Type">d</span>=<span class="Constant">"M27,-71.8314C27,-64.131 27,-54.9743 27,-46.4166"</span><span class="Identifier">/></span>
|
3343
|
+
<span class="Identifier"><</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">"black"</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">"black"</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">"30.5001,-46.4132 27,-36.4133 23.5001,-46.4133 30.5001,-46.4132"</span><span class="Identifier">/></span>
|
3344
|
+
<span class="Identifier"></g></span>
|
3345
|
+
<span class="Identifier"></g></span>
|
3346
|
+
<span class="Identifier"></svg></span>
|
3347
|
+
EOF
|
3348
|
+
</pre>
|
3349
|
+
<pre class='ruby code syntax'>
|
3350
|
+
<span class="Comment">#! ))) svg</span>
|
3351
|
+
|
3352
|
+
<span class="PreProc">def</span> <span class="Identifier">test_valid_diagram</span>
|
3353
|
+
diagram = <<-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
|
3354
|
+
</pre>
|
3355
|
+
<pre class='dot code syntax'>
|
3356
|
+
<span class="Identifier">define</span><span class="Statement">(</span>`<span class="Identifier">X</span>', `<span class="Identifier">A</span>'<span class="Statement">)</span>
|
3357
|
+
<span class="Statement">digraph</span> <span class="Statement">{</span>
|
3358
|
+
<span class="Identifier">X</span> <span class="Statement">-></span> <span class="Identifier">B</span><span class="Statement">;</span>
|
3359
|
+
<span class="Statement">}</span>
|
3360
|
+
<span class="Identifier">EOF</span>
|
3361
|
+
</pre>
|
3362
|
+
<pre class='ruby code syntax'>
|
3363
|
+
<span class="Comment">#! ))) dot</span>
|
3364
|
+
<span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram).should == <span class="Type">MINIMAL_DIAGRAM_SVG</span>
|
3365
|
+
end
|
3366
|
+
|
3367
|
+
<span class="PreProc">def</span> <span class="Identifier">test_invalid_diagram</span>
|
3368
|
+
diagram = <<-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
|
3369
|
+
</pre>
|
3370
|
+
<pre class='dot code syntax'>
|
3371
|
+
<span class="Statement">digraph</span> <span class="Statement">{</span>
|
3372
|
+
<span class="Identifier">A</span> <span class="Statement">-></span>
|
3373
|
+
<span class="Identifier">EOF</span>
|
3374
|
+
</pre>
|
3375
|
+
<pre class='ruby code syntax'>
|
3376
|
+
<span class="Comment">#! ))) dot</span>
|
3377
|
+
<span class="Statement">lambda</span> { <span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram) }.should.raise
|
3378
|
+
end
|
3379
|
+
|
3380
|
+
end
|
3381
|
+
</pre>
|
3382
|
+
</div>
|
3383
|
+
</div>
|
3384
|
+
</p>
|
3385
|
+
<p>
|
3386
|
+
And here is the implementation:
|
3387
|
+
</p>
|
3388
|
+
<p>
|
3389
|
+
<div class="named_with_containers chunk">
|
3390
|
+
<div class="chunk name">
|
3391
|
+
<a name="lib-codnar-graphviz-rb">
|
3392
|
+
<span>lib/codnar/graphviz.rb</span>
|
3393
|
+
</a>
|
3394
|
+
</div>
|
3395
|
+
<div class="chunk html">
|
3396
|
+
<pre class='ruby code syntax'>
|
3397
|
+
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">open3</span><span class="Special">"</span>
|
3398
|
+
|
3399
|
+
<span class="PreProc">module</span> <span class="Type">Codnar</span>
|
3400
|
+
|
3401
|
+
</pre>
|
3402
|
+
<table class='layout'>
|
3403
|
+
<tr>
|
3404
|
+
<td class='indentation'>
|
3405
|
+
<pre> </pre>
|
3406
|
+
</td>
|
3407
|
+
<td class='html'>
|
3408
|
+
<div class='rdoc comment markup'>
|
3409
|
+
<p>
|
3410
|
+
Generate diagrams using GraphViz.
|
3411
|
+
</p>
|
3412
|
+
</div>
|
3413
|
+
</td>
|
3414
|
+
</tr>
|
3415
|
+
</table>
|
3416
|
+
<pre class='ruby code syntax'>
|
3417
|
+
<span class="PreProc">class</span> <span class="Type">GraphViz</span>
|
3418
|
+
|
3419
|
+
</pre>
|
3420
|
+
<table class='layout'>
|
3421
|
+
<tr>
|
3422
|
+
<td class='indentation'>
|
3423
|
+
<pre> </pre>
|
3424
|
+
</td>
|
3425
|
+
<td class='html'>
|
3426
|
+
<div class='rdoc comment markup'>
|
3427
|
+
<p>
|
3428
|
+
Convert a string containing a GraphViz diagram into SVG suitable for
|
3429
|
+
embedding into the HTML documentation. We pre-process the diagram using M4
|
3430
|
+
to allow cutting down on the boilerplate (repeating the same styles in many
|
3431
|
+
nodes etc.). This should not be harmful for diagrams that do not use M4
|
3432
|
+
commands.
|
3433
|
+
</p>
|
3434
|
+
</div>
|
3435
|
+
</td>
|
3436
|
+
</tr>
|
3437
|
+
</table>
|
3438
|
+
<pre class='ruby code syntax'>
|
3439
|
+
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">to_html</span>(diagram)
|
3440
|
+
stdin, stdout, stderr = <span class="Type">Open3</span>.popen3(<span class="Special">"</span><span class="Constant">m4 | dot -Tsvg</span><span class="Special">"</span>)
|
3441
|
+
write_diagram(stdin, diagram)
|
3442
|
+
check_for_errors(stderr)
|
3443
|
+
<span class="Statement">return</span> clean_output(stdout)
|
3444
|
+
<span class="PreProc">end</span>
|
3445
|
+
|
3446
|
+
<span class="Statement">protected</span>
|
3447
|
+
|
3448
|
+
</pre>
|
3449
|
+
<table class='layout'>
|
3450
|
+
<tr>
|
3451
|
+
<td class='indentation'>
|
3452
|
+
<pre> </pre>
|
3453
|
+
</td>
|
3454
|
+
<td class='html'>
|
3455
|
+
<div class='rdoc comment markup'>
|
3456
|
+
<p>
|
3457
|
+
Send the diagram to the commands pipe.
|
3458
|
+
</p>
|
3459
|
+
</div>
|
3460
|
+
</td>
|
3461
|
+
</tr>
|
3462
|
+
</table>
|
3463
|
+
<pre class='ruby code syntax'>
|
3464
|
+
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">write_diagram</span>(stdin, diagram)
|
3465
|
+
stdin.write(diagram)
|
3466
|
+
stdin.close
|
3467
|
+
<span class="PreProc">end</span>
|
3468
|
+
|
3469
|
+
</pre>
|
3470
|
+
<table class='layout'>
|
3471
|
+
<tr>
|
3472
|
+
<td class='indentation'>
|
3473
|
+
<pre> </pre>
|
3474
|
+
</td>
|
3475
|
+
<td class='html'>
|
3476
|
+
<div class='rdoc comment markup'>
|
3477
|
+
<p>
|
3478
|
+
Ensure we got no processing errors from either m4 or dot. If we did, raise
|
3479
|
+
them, and they will be handled by the formatter wrapping code.
|
3480
|
+
</p>
|
3481
|
+
</div>
|
3482
|
+
</td>
|
3483
|
+
</tr>
|
3484
|
+
</table>
|
3485
|
+
<pre class='ruby code syntax'>
|
3486
|
+
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">check_for_errors</span>(stderr)
|
3487
|
+
errors = stderr.read
|
3488
|
+
<span class="Statement">raise</span> errors.sub(<span class="Special">/</span><span class="Constant">Error: <stdin>:</span><span class="Special">\d</span><span class="Special">+</span><span class="Constant">: </span><span class="Special">/</span>, <span class="Special">""</span>) <span class="Statement">if</span> errors != <span class="Special">""</span>
|
3489
|
+
<span class="PreProc">end</span>
|
3490
|
+
|
3491
|
+
</pre>
|
3492
|
+
<table class='layout'>
|
3493
|
+
<tr>
|
3494
|
+
<td class='indentation'>
|
3495
|
+
<pre> </pre>
|
3496
|
+
</td>
|
3497
|
+
<td class='html'>
|
3498
|
+
<div class='rdoc comment markup'>
|
3499
|
+
<p>
|
3500
|
+
Clean the SVG we got to make it suitable for embedding in HTML.
|
3501
|
+
</p>
|
3502
|
+
</div>
|
3503
|
+
</td>
|
3504
|
+
</tr>
|
3505
|
+
</table>
|
3506
|
+
<pre class='ruby code syntax'>
|
3507
|
+
<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">clean_output</span>(stdout)
|
3508
|
+
<span class="Statement">return</span> stdout.read.sub(<span class="Special">/</span><span class="Special">.</span><span class="Special">*</span><span class="Constant"><svg</span><span class="Special">/m</span>, <span class="Special">"</span><span class="Constant"><svg</span><span class="Special">"</span>).gsub(<span class="Special">/</span><span class="Special">\r</span><span class="Special">/</span>, <span class="Special">""</span>)
|
3509
|
+
<span class="PreProc">end</span>
|
3510
|
+
|
3511
|
+
end
|
3512
|
+
|
3513
|
+
end
|
3514
|
+
</pre>
|
3515
|
+
</div>
|
3516
|
+
</div>
|
3517
|
+
</p>
|
3179
3518
|
<h4>Syntax highlighting using GVIM</h4>
|
3180
3519
|
<p>
|
3181
3520
|
If you have <code>gvim</code> istalled, it is possible to use it to generate syntax
|
@@ -4382,7 +4721,7 @@ Test “splitting” documentation files.
|
|
4382
4721
|
<span class="PreProc">def</span> <span class="Identifier">configuration</span>(kind)
|
4383
4722
|
<span class="Statement">return</span> {
|
4384
4723
|
<span class="Special">"</span><span class="Constant">formatters</span><span class="Special">"</span> => {
|
4385
|
-
<span class="Special">"</span><span class="Constant">markdown</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines,
|
4724
|
+
<span class="Special">"</span><span class="Constant">markdown</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, Markdown, 'markdown')</span><span class="Special">"</span>,
|
4386
4725
|
<span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">"</span>,
|
4387
4726
|
<span class="Special">"</span><span class="Constant">rdoc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, 'RDoc')</span><span class="Special">"</span>,
|
4388
4727
|
},
|
@@ -4984,7 +5323,7 @@ preserved by escaping it and wrapping it in an HTML pre element.
|
|
4984
5323
|
<pre class='ruby code syntax'>
|
4985
5324
|
<span class="Type">SPLIT_RDOC_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
|
4986
5325
|
<span class="Special">"</span><span class="Constant">formatters</span><span class="Special">"</span> => {
|
4987
|
-
<span class="Special">"</span><span class="Constant">doc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines,
|
5326
|
+
<span class="Special">"</span><span class="Constant">doc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, RDoc)</span><span class="Special">"</span>,
|
4988
5327
|
<span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">"</span>,
|
4989
5328
|
}
|
4990
5329
|
)
|
@@ -5007,7 +5346,30 @@ preserved by escaping it and wrapping it in an HTML pre element.
|
|
5007
5346
|
<pre class='ruby code syntax'>
|
5008
5347
|
<span class="Type">SPLIT_MARKDOWN_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
|
5009
5348
|
<span class="Special">"</span><span class="Constant">formatters</span><span class="Special">"</span> => {
|
5010
|
-
<span class="Special">"</span><span class="Constant">doc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines,
|
5349
|
+
<span class="Special">"</span><span class="Constant">doc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, Markdown, 'markdown')</span><span class="Special">"</span>,
|
5350
|
+
<span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">"</span>,
|
5351
|
+
}
|
5352
|
+
)
|
5353
|
+
|
5354
|
+
</pre>
|
5355
|
+
<table class='layout'>
|
5356
|
+
<tr>
|
5357
|
+
<td class='indentation'>
|
5358
|
+
<pre></pre>
|
5359
|
+
</td>
|
5360
|
+
<td class='html'>
|
5361
|
+
<div class='rdoc comment markup'>
|
5362
|
+
<p>
|
5363
|
+
“Split” a documentation file containing a GraphViz diagram.
|
5364
|
+
</p>
|
5365
|
+
</div>
|
5366
|
+
</td>
|
5367
|
+
</tr>
|
5368
|
+
</table>
|
5369
|
+
<pre class='ruby code syntax'>
|
5370
|
+
<span class="Type">SPLIT_GRAPHVIZ_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
|
5371
|
+
<span class="Special">"</span><span class="Constant">formatters</span><span class="Special">"</span> => {
|
5372
|
+
<span class="Special">"</span><span class="Constant">doc</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::GraphViz, 'graphviz')</span><span class="Special">"</span>,
|
5011
5373
|
<span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">"</span>,
|
5012
5374
|
}
|
5013
5375
|
)
|
@@ -5916,7 +6278,7 @@ configuration that classifies some lines as <tt>comment</tt>.
|
|
5916
6278
|
<pre class='ruby code syntax'>
|
5917
6279
|
<span class="Type">FORMAT_MARKDOWN_COMMENTS</span> = {
|
5918
6280
|
<span class="Special">"</span><span class="Constant">formatters</span><span class="Special">"</span> => {
|
5919
|
-
<span class="Special">"</span><span class="Constant">comment</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines,
|
6281
|
+
<span class="Special">"</span><span class="Constant">comment</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.markup_lines_to_html(lines, Markdown, 'markdown')</span><span class="Special">"</span>,
|
5920
6282
|
<span class="Special">"</span><span class="Constant">unindented_html</span><span class="Special">"</span> => <span class="Special">"</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">"</span>,
|
5921
6283
|
},
|
5922
6284
|
}
|
@@ -8398,6 +8760,7 @@ convenient list of all of Codnar's parts and dependencies:
|
|
8398
8760
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/application</span><span class="Special">"</span>
|
8399
8761
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/cache</span><span class="Special">"</span>
|
8400
8762
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/formatter</span><span class="Special">"</span>
|
8763
|
+
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/graphviz</span><span class="Special">"</span>
|
8401
8764
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/grouper</span><span class="Special">"</span>
|
8402
8765
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/gvim</span><span class="Special">"</span>
|
8403
8766
|
<span class="PreProc">require</span> <span class="Special">"</span><span class="Constant">codnar/merger</span><span class="Special">"</span>
|
@@ -10039,7 +10402,11 @@ HTML islands.
|
|
10039
10402
|
<span class="Special">"</span><span class="Constant">classify_source_code:ruby</span><span class="Special">"</span>,
|
10040
10403
|
<span class="Special">"</span><span class="Constant">format_code_gvim_css:ruby</span><span class="Special">"</span>,
|
10041
10404
|
<span class="Special">"</span><span class="Constant">classify_nested_code:ruby:html</span><span class="Special">"</span>,
|
10405
|
+
<span class="Special">"</span><span class="Constant">classify_nested_code:ruby:dot</span><span class="Special">"</span>,
|
10406
|
+
<span class="Special">"</span><span class="Constant">classify_nested_code:ruby:svg</span><span class="Special">"</span>,
|
10042
10407
|
<span class="Special">"</span><span class="Constant">format_code_gvim_css:html</span><span class="Special">"</span>,
|
10408
|
+
<span class="Special">"</span><span class="Constant">format_code_gvim_css:dot</span><span class="Special">"</span>,
|
10409
|
+
<span class="Special">"</span><span class="Constant">format_code_gvim_css:svg</span><span class="Special">"</span>,
|
10043
10410
|
<span class="Special">"</span><span class="Constant">classify_shell_comments</span><span class="Special">"</span>,
|
10044
10411
|
<span class="Special">"</span><span class="Constant">format_rdoc_comments</span><span class="Special">"</span>,
|
10045
10412
|
], [
|
data/doc/dataflow.dot
ADDED
@@ -0,0 +1,16 @@
|
|
1
|
+
define(`FileNodeStyle', `shape = box')
|
2
|
+
define(`ProcNodeStyle', `shape = ellipse')
|
3
|
+
digraph "Codnar Dataflow" {
|
4
|
+
rankdir = LR;
|
5
|
+
Documentation [ FileNodeStyle ];
|
6
|
+
Sources [ FileNodeStyle ];
|
7
|
+
Split [ ProcNodeStyle ];
|
8
|
+
Chunks [ FileNodeStyle ];
|
9
|
+
Weave [ ProcNodeStyle ];
|
10
|
+
HTML [ FileNodeStyle ];
|
11
|
+
Build [ ProcNodeStyle ];
|
12
|
+
Program [ FileNodeStyle ];
|
13
|
+
Documentation -> Split;
|
14
|
+
Sources -> Split -> Chunks -> Weave -> HTML;
|
15
|
+
Sources -> Build -> Program;
|
16
|
+
}
|
data/doc/system.markdown
CHANGED
@@ -1,3 +1,10 @@
|
|
1
|
+
## Data Flow ##
|
2
|
+
|
3
|
+
Here is a diagram showing the overall data flow in a system documented with
|
4
|
+
Codnar:
|
5
|
+
|
6
|
+
[[doc/dataflow.dot|plain_chunk]]
|
7
|
+
|
1
8
|
## Splitting files into chunks ##
|
2
9
|
|
3
10
|
Codnar makes the reasonable assumption that each source file can be effectively
|
@@ -153,6 +160,27 @@ messy. We therefore clean it up:
|
|
153
160
|
|
154
161
|
[[Clean html|named_chunk_with_containers]]
|
155
162
|
|
163
|
+
#### Generating diagrams using GraphViz ####
|
164
|
+
|
165
|
+
If you have `graphviz` installed, it is possible to use it to generate SVG
|
166
|
+
diagrams that can be embedded directly into the HTML. This is implemented as an
|
167
|
+
additional formatter; in principle, you this allows embeding the GraphViz
|
168
|
+
directives directly in the code, but in practice people prefer keeping the
|
169
|
+
diagrams as separate files.
|
170
|
+
|
171
|
+
We pre-process the GraphViz directives using the `m4` macro processor. This
|
172
|
+
allows dramatically reducing the amount of repeated boilerplate in the diagram
|
173
|
+
definitions, by defining macros for node and edge styles and, if desired, more
|
174
|
+
advanced techniques.
|
175
|
+
|
176
|
+
Here is a simple test that demonstrates generating SVG from a GraphViz diagram:
|
177
|
+
|
178
|
+
[[test/graphviz_diagrams.rb|named_chunk_with_containers]]
|
179
|
+
|
180
|
+
And here is the implementation:
|
181
|
+
|
182
|
+
[[lib/codnar/graphviz.rb|named_chunk_with_containers]]
|
183
|
+
|
156
184
|
#### Syntax highlighting using GVIM ####
|
157
185
|
|
158
186
|
If you have `gvim` istalled, it is possible to use it to generate syntax
|
data/lib/codnar.rb
CHANGED
data/lib/codnar/formatter.rb
CHANGED
@@ -164,10 +164,11 @@ module Codnar
|
|
164
164
|
end
|
165
165
|
|
166
166
|
# Convert a sequence of marked-up classified lines to (unindented) HTML
|
167
|
-
def self.markup_lines_to_html(lines, klass)
|
167
|
+
def self.markup_lines_to_html(lines, klass, css_class = nil)
|
168
168
|
implementation = String === klass ? Kernel.const_get(klass) : klass
|
169
|
+
css_class ||= implementation.to_s.downcase.gsub("::", "-")
|
169
170
|
return Formatter.merge_lines(lines, "unindented_html", "") do |payload|
|
170
|
-
( "<div class='#{
|
171
|
+
( "<div class='#{css_class} #{lines[0].kind} markup'>\n" \
|
171
172
|
+ implementation.to_html(payload) \
|
172
173
|
+ "</div>" )
|
173
174
|
end
|
@@ -0,0 +1,42 @@
|
|
1
|
+
require "open3"
|
2
|
+
|
3
|
+
module Codnar
|
4
|
+
|
5
|
+
# Generate diagrams using GraphViz.
|
6
|
+
class GraphViz
|
7
|
+
|
8
|
+
# Convert a string containing a GraphViz diagram into SVG suitable for
|
9
|
+
# embedding into the HTML documentation. We pre-process the diagram using
|
10
|
+
# M4 to allow cutting down on the boilerplate (repeating the same styles in
|
11
|
+
# many nodes etc.). This should not be harmful for diagrams that do not use
|
12
|
+
# M4 commands.
|
13
|
+
def self.to_html(diagram)
|
14
|
+
stdin, stdout, stderr = Open3.popen3("m4 | dot -Tsvg")
|
15
|
+
write_diagram(stdin, diagram)
|
16
|
+
check_for_errors(stderr)
|
17
|
+
return clean_output(stdout)
|
18
|
+
end
|
19
|
+
|
20
|
+
protected
|
21
|
+
|
22
|
+
# Send the diagram to the commands pipe.
|
23
|
+
def self.write_diagram(stdin, diagram)
|
24
|
+
stdin.write(diagram)
|
25
|
+
stdin.close
|
26
|
+
end
|
27
|
+
|
28
|
+
# Ensure we got no processing errors from either m4 or dot. If we did,
|
29
|
+
# raise them, and they will be handled by the formatter wrapping code.
|
30
|
+
def self.check_for_errors(stderr)
|
31
|
+
errors = stderr.read
|
32
|
+
raise errors.sub(/Error: <stdin>:\d+: /, "") if errors != ""
|
33
|
+
end
|
34
|
+
|
35
|
+
# Clean the SVG we got to make it suitable for embedding in HTML.
|
36
|
+
def self.clean_output(stdout)
|
37
|
+
return stdout.read.sub(/.*<svg/m, "<svg").gsub(/\r/, "")
|
38
|
+
end
|
39
|
+
|
40
|
+
end
|
41
|
+
|
42
|
+
end
|
data/lib/codnar/markdown.rb
CHANGED
@@ -24,7 +24,7 @@ protected
|
|
24
24
|
|
25
25
|
# Expand "[[chunk|template]]" to HTML embed tags. Use identifiers instead of
|
26
26
|
# names in the +src+ field for safety, unless the template is a magical file
|
27
|
-
# template, in which case we must preserve the file path
|
27
|
+
# template, in which case we must preserve the file path.
|
28
28
|
def self.embed_chunks(markdown)
|
29
29
|
return markdown.gsub(/\[\[(.*?)\|(.*?)\]\]/) do
|
30
30
|
src = $1
|
@@ -39,7 +39,7 @@ module Codnar
|
|
39
39
|
# "Split" a documentation file containing pure RDoc documentation.
|
40
40
|
SPLIT_RDOC_DOCUMENTATION = SPLIT_HTML_DOCUMENTATION.deep_merge(
|
41
41
|
"formatters" => {
|
42
|
-
"doc" => "Formatter.markup_lines_to_html(lines,
|
42
|
+
"doc" => "Formatter.markup_lines_to_html(lines, RDoc)",
|
43
43
|
"unindented_html" => "Formatter.unindented_lines_to_html(lines)",
|
44
44
|
}
|
45
45
|
)
|
@@ -47,7 +47,15 @@ module Codnar
|
|
47
47
|
# "Split" a documentation file containing pure Markdown documentation.
|
48
48
|
SPLIT_MARKDOWN_DOCUMENTATION = SPLIT_HTML_DOCUMENTATION.deep_merge(
|
49
49
|
"formatters" => {
|
50
|
-
"doc" => "Formatter.markup_lines_to_html(lines,
|
50
|
+
"doc" => "Formatter.markup_lines_to_html(lines, Markdown, 'markdown')",
|
51
|
+
"unindented_html" => "Formatter.unindented_lines_to_html(lines)",
|
52
|
+
}
|
53
|
+
)
|
54
|
+
|
55
|
+
# "Split" a documentation file containing a GraphViz diagram.
|
56
|
+
SPLIT_GRAPHVIZ_DOCUMENTATION = SPLIT_HTML_DOCUMENTATION.deep_merge(
|
57
|
+
"formatters" => {
|
58
|
+
"doc" => "Formatter.markup_lines_to_html(lines, Codnar::GraphViz, 'graphviz')",
|
51
59
|
"unindented_html" => "Formatter.unindented_lines_to_html(lines)",
|
52
60
|
}
|
53
61
|
)
|
@@ -278,7 +286,7 @@ module Codnar
|
|
278
286
|
# configuration that classifies some lines as +comment+.
|
279
287
|
FORMAT_MARKDOWN_COMMENTS = {
|
280
288
|
"formatters" => {
|
281
|
-
"comment" => "Formatter.markup_lines_to_html(lines,
|
289
|
+
"comment" => "Formatter.markup_lines_to_html(lines, Markdown, 'markdown')",
|
282
290
|
"unindented_html" => "Formatter.unindented_lines_to_html(lines)",
|
283
291
|
},
|
284
292
|
}
|
data/lib/codnar/version.rb
CHANGED
@@ -0,0 +1,53 @@
|
|
1
|
+
require "codnar"
|
2
|
+
require "test/spec"
|
3
|
+
|
4
|
+
# Test highlighting syntax using GVim.
|
5
|
+
class TestGraphVizDiagrams < Test::Unit::TestCase
|
6
|
+
|
7
|
+
MINIMAL_DIAGRAM_SVG = <<-EOF.unindent #! ((( svg
|
8
|
+
<svg width="62pt" height="116pt"
|
9
|
+
viewBox="0.00 0.00 62.00 116.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
10
|
+
<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 112)">
|
11
|
+
<title>_anonymous_0</title>
|
12
|
+
<polygon fill="white" stroke="white" points="-4,5 -4,-112 59,-112 59,5 -4,5"/>
|
13
|
+
<!-- A -->
|
14
|
+
<g id="node1" class="node"><title>A</title>
|
15
|
+
<ellipse fill="none" stroke="black" cx="27" cy="-90" rx="27" ry="18"/>
|
16
|
+
<text text-anchor="middle" x="27" y="-85.4" font-family="Times New Roman,serif" font-size="14.00">A</text>
|
17
|
+
</g>
|
18
|
+
<!-- B -->
|
19
|
+
<g id="node3" class="node"><title>B</title>
|
20
|
+
<ellipse fill="none" stroke="black" cx="27" cy="-18" rx="27" ry="18"/>
|
21
|
+
<text text-anchor="middle" x="27" y="-13.4" font-family="Times New Roman,serif" font-size="14.00">B</text>
|
22
|
+
</g>
|
23
|
+
<!-- A->B -->
|
24
|
+
<g id="edge2" class="edge"><title>A->B</title>
|
25
|
+
<path fill="none" stroke="black" d="M27,-71.8314C27,-64.131 27,-54.9743 27,-46.4166"/>
|
26
|
+
<polygon fill="black" stroke="black" points="30.5001,-46.4132 27,-36.4133 23.5001,-46.4133 30.5001,-46.4132"/>
|
27
|
+
</g>
|
28
|
+
</g>
|
29
|
+
</svg>
|
30
|
+
EOF
|
31
|
+
#! ))) svg
|
32
|
+
|
33
|
+
def test_valid_diagram
|
34
|
+
diagram = <<-EOF.unindent #! ((( dot
|
35
|
+
define(`X', `A')
|
36
|
+
digraph {
|
37
|
+
X -> B;
|
38
|
+
}
|
39
|
+
EOF
|
40
|
+
#! ))) dot
|
41
|
+
Codnar::GraphViz.to_html(diagram).should == MINIMAL_DIAGRAM_SVG
|
42
|
+
end
|
43
|
+
|
44
|
+
def test_invalid_diagram
|
45
|
+
diagram = <<-EOF.unindent #! ((( dot
|
46
|
+
digraph {
|
47
|
+
A ->
|
48
|
+
EOF
|
49
|
+
#! ))) dot
|
50
|
+
lambda { Codnar::GraphViz.to_html(diagram) }.should.raise
|
51
|
+
end
|
52
|
+
|
53
|
+
end
|
data/test/split_documentation.rb
CHANGED
@@ -69,7 +69,7 @@ protected
|
|
69
69
|
def configuration(kind)
|
70
70
|
return {
|
71
71
|
"formatters" => {
|
72
|
-
"markdown" => "Formatter.markup_lines_to_html(lines,
|
72
|
+
"markdown" => "Formatter.markup_lines_to_html(lines, Markdown, 'markdown')",
|
73
73
|
"unindented_html" => "Formatter.unindented_lines_to_html(lines)",
|
74
74
|
"rdoc" => "Formatter.markup_lines_to_html(lines, 'RDoc')",
|
75
75
|
},
|
metadata
CHANGED
@@ -1,13 +1,13 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: codnar
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
hash:
|
4
|
+
hash: 157
|
5
5
|
prerelease:
|
6
6
|
segments:
|
7
7
|
- 0
|
8
8
|
- 1
|
9
|
-
-
|
10
|
-
version: 0.1.
|
9
|
+
- 67
|
10
|
+
version: 0.1.67
|
11
11
|
platform: ruby
|
12
12
|
authors:
|
13
13
|
- Oren Ben-Kiki
|
@@ -15,7 +15,7 @@ autorequire:
|
|
15
15
|
bindir: bin
|
16
16
|
cert_chain: []
|
17
17
|
|
18
|
-
date: 2011-
|
18
|
+
date: 2011-09-13 00:00:00 Z
|
19
19
|
dependencies:
|
20
20
|
- !ruby/object:Gem::Dependency
|
21
21
|
name: andand
|
@@ -226,6 +226,7 @@ files:
|
|
226
226
|
- lib/codnar/data/yui/README.txt
|
227
227
|
- lib/codnar/data/yui/reset.css
|
228
228
|
- lib/codnar/formatter.rb
|
229
|
+
- lib/codnar/graphviz.rb
|
229
230
|
- lib/codnar/grouper.rb
|
230
231
|
- lib/codnar/gvim.rb
|
231
232
|
- lib/codnar/hash_extensions.rb
|
@@ -248,6 +249,7 @@ files:
|
|
248
249
|
- lib/codnar/weave_configurations.rb
|
249
250
|
- lib/codnar/writer.rb
|
250
251
|
- lib/codnar.rb
|
252
|
+
- doc/dataflow.dot
|
251
253
|
- doc/logo.png
|
252
254
|
- doc/root.html
|
253
255
|
- doc/story.markdown
|
@@ -263,6 +265,7 @@ files:
|
|
263
265
|
- test/format_code_sunlight_configurations.rb
|
264
266
|
- test/format_comment_configurations.rb
|
265
267
|
- test/format_lines.rb
|
268
|
+
- test/graphviz_diagrams.rb
|
266
269
|
- test/group_lines.rb
|
267
270
|
- test/gvim_highlight_syntax.rb
|
268
271
|
- test/identify_chunks.rb
|
@@ -296,7 +299,7 @@ licenses: []
|
|
296
299
|
post_install_message:
|
297
300
|
rdoc_options:
|
298
301
|
- --title
|
299
|
-
- Code Narrator 0.1.
|
302
|
+
- Code Narrator 0.1.67
|
300
303
|
- --main
|
301
304
|
- README.rdoc
|
302
305
|
- --line-numbers
|
@@ -339,6 +342,7 @@ test_files:
|
|
339
342
|
- test/format_code_sunlight_configurations.rb
|
340
343
|
- test/format_comment_configurations.rb
|
341
344
|
- test/format_lines.rb
|
345
|
+
- test/graphviz_diagrams.rb
|
342
346
|
- test/group_lines.rb
|
343
347
|
- test/gvim_highlight_syntax.rb
|
344
348
|
- test/identify_chunks.rb
|