Skip to content
This repository
Browse code

added top_level_readme option

  • Loading branch information...
commit f0159e58aa2af1dcb9b02d7747a0c44ca188f663 1 parent e7efc59
authored March 26, 2011
4  Makefile
@@ -8,5 +8,5 @@ compile:
8 8
 clean:
9 9
 	./rebar clean
10 10
 
11  
-doc:
12  
-	./rebar doc
  11
+doc: compile
  12
+	./make_doc
103  README_top.md
Source Rendered
... ...
@@ -0,0 +1,103 @@
  1
+
  2
+
  3
+<h1>The edown application</h1>
  4
+
  5
+The edown application
  6
+=====================
  7
+
  8
+Status:
  9
+------
  10
+More-or-less readable Markdown can be generated.
  11
+
  12
+Copyright (c) 2010 Erlang Solutions Ltd
  13
+
  14
+
  15
+__Authors:__ [`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com).
  16
+
  17
+
  18
+Status:
  19
+------
  20
+More-or-less readable Markdown can be generated.
  21
+A doclet needs to be written that also creates 
  22
+a markdown-based index and overview. Currently, the 
  23
+edoc_doclet creates an index.html and overview.html,
  24
+which do not point to the .md files.
  25
+
  26
+
  27
+
  28
+To generate markdown edoc, run:
  29
+
  30
+
  31
+<pre>
  32
+edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
  33
+</pre>
  34
+
  35
+
  36
+
  37
+
  38
+The `edown_xmerl` module is used as an xmerl export module.
  39
+It converts xmerl's "simple xml" to Markdown syntax. Note that
  40
+GH-flavored Markdown allows HTML markup (at least common tags),
  41
+but doesn't expand markdown markup inside HTML markup, so the 
  42
+`edown_xmerl` module has to know the context in which it operates.
  43
+
  44
+
  45
+
  46
+NOTE
  47
+====
  48
+EDoc provides a plugin structure, so that one may specify own 
  49
+layout modules, export modules, and doclets. However, there is 
  50
+some overlap esp. between the layout and doclet modules, and 
  51
+several functions are expected to produce files on their own.
  52
+This causes a problem for EDown, since it cannot handle frames.
  53
+Instead, it would probably like to create one overview file with
  54
+different sections. It would have been better to have a framework
  55
+where some plugin functions identify the different files to be 
  56
+written, and the outline of each, other plugins convert to suitable
  57
+content representation (e.g. HTML or Markdown), and EDoc then 
  58
+writes the files necessary.
  59
+
  60
+
  61
+
  62
+For now, EDown focuses on producing reasonable Markdown, rather
  63
+than complying fully with the plugin framework. That is, the 
  64
+edown_doclet module will not go out of its way to function together
  65
+with any other layout module than edown_layout, and vice versa.
  66
+
  67
+
  68
+
  69
+markedoc
  70
+========
  71
+
  72
+
  73
+
  74
+The sed script bin/markedoc works in the opposite direction and converts 
  75
+your `README.md` to an `EDoc` file. 
  76
+
  77
+
  78
+
  79
+See [bin/MARKEDOC-README.md](edown/blob/master/bin/MARKEDOC-README.md).
  80
+
  81
+
  82
+
  83
+**FreeBSD, Mac OS X**
  84
+`$ sed -E -f markedoc.sed <markdown file> > <edoc file>`
  85
+
  86
+
  87
+
  88
+**Linux**
  89
+`$ sed -r -f markedoc.sed <markdown file> > <edoc file>`
  90
+
  91
+
  92
+
  93
+
  94
+<h2 class="indextitle">Modules</h2>
  95
+
  96
+
  97
+
  98
+<table width="100%" border="0" summary="list of modules">
  99
+<tr><td><a href="edown/blob/master/edown_doclet.md" class="module">edown_doclet</a></td></tr>
  100
+<tr><td><a href="edown/blob/master/edown_layout.md" class="module">edown_layout</a></td></tr>
  101
+<tr><td><a href="edown/blob/master/edown_lib.md" class="module">edown_lib</a></td></tr>
  102
+<tr><td><a href="edown/blob/master/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
  103
+
2  doc/edown_doclet.md
Source Rendered
@@ -152,4 +152,4 @@ will be copied to the target directory.
152 152
 
153 153
 
154 154
 
155  
-_Generated by EDoc, Mar 25 2011, 22:22:58._
  155
+_Generated by EDoc, Mar 26 2011, 14:27:05._
4  doc/edown_layout.md
Source Rendered
@@ -106,7 +106,7 @@ specified, no stylesheet reference will be generated.
106 106
 
107 107
 
108 108
 
109  
-<dt><code>{sort_functions, <a href="#type-boolean">boolean()</a>}</code>
  109
+<dt><code>{sort_functions, boolean()}</code>
110 110
 </dt>
111 111
 
112 112
 
@@ -166,4 +166,4 @@ __See also:__ [//edoc/edoc:layout/2](http://www.erlang.org/doc/man/edoc.html#lay
166 166
 
167 167
 
168 168
 
169  
-_Generated by EDoc, Mar 25 2011, 22:22:58._
  169
+_Generated by EDoc, Mar 26 2011, 14:27:04._
2  doc/edown_lib.md
Source Rendered
@@ -61,4 +61,4 @@ __Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erla
61 61
 
62 62
 
63 63
 
64  
-_Generated by EDoc, Mar 25 2011, 22:22:58._
  64
+_Generated by EDoc, Mar 26 2011, 14:27:04._
2  doc/edown_xmerl.md
Source Rendered
@@ -70,4 +70,4 @@ __Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erla
70 70
 
71 71
 
72 72
 
73  
-_Generated by EDoc, Mar 25 2011, 22:22:58._
  73
+_Generated by EDoc, Mar 26 2011, 14:27:04._
22  make_doc
... ...
@@ -0,0 +1,22 @@
  1
+#!/usr/bin/env escript
  2
+%% -*- erlang -*-
  3
+
  4
+%% edown is designed to work well with rebar, but in order to use edown
  5
+%% to document itself, we need to explicitly set the path to ebin/, so
  6
+%% that we pick up the newly built edown doclet. I haven't found a way
  7
+%% to do this with 'rebar doc'.
  8
+%%
  9
+main([]) ->
  10
+    code:add_patha("ebin"),
  11
+    R = edoc:application(edown, ".",
  12
+			 [{doclet, edown_doclet},
  13
+			  {src_path, ["src"]},
  14
+			  {app_default,"http://www.erlang.org/doc/man"},
  15
+			  {top_level_readme, {".", "README_top.md"}}]),
  16
+    case R of
  17
+	ok ->
  18
+	    halt();
  19
+	Err ->
  20
+	    io:fwrite("~p~n", [Err]),
  21
+	    halt(1)
  22
+    end.
8  rebar.config
@@ -7,6 +7,8 @@
7 7
 
8 8
 {clean_files, ["*~","*/*~","ebin/*.beam"]}.
9 9
 
10  
-{edoc_opts, [{doclet, edown_doclet},
11  
-             {src_path, ["src", "test"]},
12  
-	     {app_default,"http://www.erlang.org/doc/man"}]}.
  10
+%% This is a reasonable set of options to use for edown, but edown
  11
+%% doesn't actually use rebar to make its own docs.
  12
+%% {edoc_opts, [{doclet, edown_doclet},
  13
+%%              {src_path, ["src", "test"]},
  14
+%%  	        {app_default,"http://www.erlang.org/doc/man"}]}.
2  src/edown.app.src
@@ -17,7 +17,7 @@
17 17
 
18 18
 {application, edown,
19 19
  [
20  
-  {vsn, "0.1"},
  20
+  {vsn, "0.2.0"},
21 21
   {description, "Markdown extension for EDoc"},
22 22
   {applications, [kernel, stdlib]},
23 23
   {mod, {jobs_app, []}},
64  src/edown_doclet.erl
@@ -141,13 +141,13 @@ gen(Sources, App, Packages, Modules, FileMap, Ctxt) ->
141 141
     edoc_lib:write_info_file(App, Packages, Modules1, Dir),
142 142
     copy_stylesheet(Dir, Options),
143 143
     copy_image(Dir),
  144
+    make_top_level_README(Data, App, Options),
144 145
     %% handle postponed error during processing of source files
145 146
     case Error of
146 147
 	true -> exit(error);
147 148
 	false -> ok
148 149
     end.
149 150
 
150  
-
151 151
 set_app_default(Opts) ->
152 152
     case lists:keyfind(app_default,1,Opts) of
153 153
 	false ->
@@ -156,8 +156,68 @@ set_app_default(Opts) ->
156 156
 	    Opts
157 157
     end.
158 158
 
  159
+make_top_level_README(Data, App, Options) ->
  160
+    case proplists:get_value(top_level_readme, Options) of
  161
+	undefined ->
  162
+	    ok;
  163
+	{Dir, Filename} ->
  164
+	    case App of 
  165
+		?NO_APP ->
  166
+		    erlang:error(missing_app_name, [Data,App,Options]);
  167
+		_ ->
  168
+		    make_top_level_README(Data, App, Dir, Filename)
  169
+	    end
  170
+    end.
  171
+
  172
+make_top_level_README(Data, App, Dir, F) ->
  173
+    Branch = get_git_branch(),
  174
+    Exp = [xmerl_lib:expand_element(D) || D <- Data],
  175
+    New = [xmerl_lib:mapxml(
  176
+	     fun(#xmlElement{name = a,
  177
+			     attributes = Attrs} = E) ->
  178
+		     case redirect_href(Attrs, App, Branch) of
  179
+			 {true, Attrs1} ->
  180
+			     E#xmlElement{attributes = Attrs1};
  181
+			 false ->
  182
+			     E
  183
+		     end;
  184
+		(Other) ->
  185
+		     Other
  186
+	     end, Exp1) || Exp1 <- Exp],
  187
+    Text = xmerl:export_simple_content(New, edown_xmerl),
  188
+    edoc_lib:write_file(Text, Dir, F).
  189
+
  190
+redirect_href(Attrs, App, Branch) ->
  191
+    AppBlob = atom_to_list(App) ++ "/blob/" ++ Branch ++ "/",
  192
+    case lists:keyfind(href, #xmlAttribute.name, Attrs) of
  193
+	false ->
  194
+	    false;
  195
+	#xmlAttribute{value = "/" ++ _} ->
  196
+	    false;
  197
+	#xmlAttribute{value = Href} = A ->
  198
+	    case re:run(Href, ":", []) of
  199
+		{match, _} ->
  200
+		    false;
  201
+		nomatch ->
  202
+		    HRef1 = AppBlob ++ Href,
  203
+		    {true,
  204
+		     lists:keyreplace(
  205
+		       href, #xmlAttribute.name, Attrs,
  206
+		       A#xmlAttribute{value = HRef1})}
  207
+	    end
  208
+    end.
  209
+
  210
+get_git_branch() ->
  211
+    case os:cmd("git branch | awk '/\\*/ {print $2}'") of
  212
+        [_,_|_] = Res ->
  213
+            %% trailing newline expected - remove.
  214
+            lists:reverse(tl(lists:reverse(Res)));
  215
+        Other ->
  216
+            erlang:error({cannot_get_git_branch, Other})
  217
+    end.
  218
+
159 219
 %% Tried to display logo in a table on top of page, but not working.
160  
-%% Presumably, this hits some limitation of GFM
  220
+%% Presumably, this hits some limitation of Markdown
161 221
 %%
162 222
 %% logo() ->
163 223
 %%     {img, [{src, "erlang.png"},{alt,["Erlang logo"]}],[]}.
2  src/edown_xmerl.erl
@@ -191,7 +191,7 @@ within_html(Tags) ->
191 191
 needs_html(T) ->
192 192
     needs_html(T, []).
193 193
 
194  
-needs_html(T, Attrs) ->
  194
+needs_html(T, _Attrs) ->
195 195
     lists:member(T, [table,'div',h1,h2,h3,h4,dd,dt,local_defs,localdef]).
196 196
 
197 197
 no_nl(S) ->

0 notes on commit f0159e5

Please sign in to comment.
Something went wrong with that request. Please try again.