Permalink
Browse files

added top_level_readme option

  • Loading branch information...
1 parent e7efc59 commit f0159e58aa2af1dcb9b02d7747a0c44ca188f663 Ulf Wiger committed Mar 26, 2011
Showing with 201 additions and 14 deletions.
  1. +2 −2 Makefile
  2. +103 −0 README_top.md
  3. +1 −1 doc/edown_doclet.md
  4. +2 −2 doc/edown_layout.md
  5. +1 −1 doc/edown_lib.md
  6. +1 −1 doc/edown_xmerl.md
  7. +22 −0 make_doc
  8. +5 −3 rebar.config
  9. +1 −1 src/edown.app.src
  10. +62 −2 src/edown_doclet.erl
  11. +1 −1 src/edown_xmerl.erl
View
@@ -8,5 +8,5 @@ compile:
clean:
./rebar clean
-doc:
- ./rebar doc
+doc: compile
+ ./make_doc
View
@@ -0,0 +1,103 @@
+
+
+<h1>The edown application</h1>
+
+The edown application
+=====================
+
+Status:
+------
+More-or-less readable Markdown can be generated.
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+
+__Authors:__ [`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com).
+
+
+Status:
+------
+More-or-less readable Markdown can be generated.
+A doclet needs to be written that also creates
+a markdown-based index and overview. Currently, the
+edoc_doclet creates an index.html and overview.html,
+which do not point to the .md files.
+
+
+
+To generate markdown edoc, run:
+
+
+<pre>
+edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
+</pre>
+
+
+
+
+The `edown_xmerl` module is used as an xmerl export module.
+It converts xmerl's "simple xml" to Markdown syntax. Note that
+GH-flavored Markdown allows HTML markup (at least common tags),
+but doesn't expand markdown markup inside HTML markup, so the
+`edown_xmerl` module has to know the context in which it operates.
+
+
+
+NOTE
+====
+EDoc provides a plugin structure, so that one may specify own
+layout modules, export modules, and doclets. However, there is
+some overlap esp. between the layout and doclet modules, and
+several functions are expected to produce files on their own.
+This causes a problem for EDown, since it cannot handle frames.
+Instead, it would probably like to create one overview file with
+different sections. It would have been better to have a framework
+where some plugin functions identify the different files to be
+written, and the outline of each, other plugins convert to suitable
+content representation (e.g. HTML or Markdown), and EDoc then
+writes the files necessary.
+
+
+
+For now, EDown focuses on producing reasonable Markdown, rather
+than complying fully with the plugin framework. That is, the
+edown_doclet module will not go out of its way to function together
+with any other layout module than edown_layout, and vice versa.
+
+
+
+markedoc
+========
+
+
+
+The sed script bin/markedoc works in the opposite direction and converts
+your `README.md` to an `EDoc` file.
+
+
+
+See [bin/MARKEDOC-README.md](edown/blob/master/bin/MARKEDOC-README.md).
+
+
+
+**FreeBSD, Mac OS X**
+`$ sed -E -f markedoc.sed <markdown file> > <edoc file>`
+
+
+
+**Linux**
+`$ sed -r -f markedoc.sed <markdown file> > <edoc file>`
+
+
+
+
+<h2 class="indextitle">Modules</h2>
+
+
+
+<table width="100%" border="0" summary="list of modules">
+<tr><td><a href="edown/blob/master/edown_doclet.md" class="module">edown_doclet</a></td></tr>
+<tr><td><a href="edown/blob/master/edown_layout.md" class="module">edown_layout</a></td></tr>
+<tr><td><a href="edown/blob/master/edown_lib.md" class="module">edown_lib</a></td></tr>
+<tr><td><a href="edown/blob/master/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
+
View
@@ -152,4 +152,4 @@ will be copied to the target directory.
-_Generated by EDoc, Mar 25 2011, 22:22:58._
+_Generated by EDoc, Mar 26 2011, 14:27:05._
View
@@ -106,7 +106,7 @@ specified, no stylesheet reference will be generated.
-<dt><code>{sort_functions, <a href="#type-boolean">boolean()</a>}</code>
+<dt><code>{sort_functions, boolean()}</code>
</dt>
@@ -166,4 +166,4 @@ __See also:__ [//edoc/edoc:layout/2](http://www.erlang.org/doc/man/edoc.html#lay
-_Generated by EDoc, Mar 25 2011, 22:22:58._
+_Generated by EDoc, Mar 26 2011, 14:27:04._
View
@@ -61,4 +61,4 @@ __Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erla
-_Generated by EDoc, Mar 25 2011, 22:22:58._
+_Generated by EDoc, Mar 26 2011, 14:27:04._
View
@@ -70,4 +70,4 @@ __Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erla
-_Generated by EDoc, Mar 25 2011, 22:22:58._
+_Generated by EDoc, Mar 26 2011, 14:27:04._
View
@@ -0,0 +1,22 @@
+#!/usr/bin/env escript
+%% -*- erlang -*-
+
+%% edown is designed to work well with rebar, but in order to use edown
+%% to document itself, we need to explicitly set the path to ebin/, so
+%% that we pick up the newly built edown doclet. I haven't found a way
+%% to do this with 'rebar doc'.
+%%
+main([]) ->
+ code:add_patha("ebin"),
+ R = edoc:application(edown, ".",
+ [{doclet, edown_doclet},
+ {src_path, ["src"]},
+ {app_default,"http://www.erlang.org/doc/man"},
+ {top_level_readme, {".", "README_top.md"}}]),
+ case R of
+ ok ->
+ halt();
+ Err ->
+ io:fwrite("~p~n", [Err]),
+ halt(1)
+ end.
View
@@ -7,6 +7,8 @@
{clean_files, ["*~","*/*~","ebin/*.beam"]}.
-{edoc_opts, [{doclet, edown_doclet},
- {src_path, ["src", "test"]},
- {app_default,"http://www.erlang.org/doc/man"}]}.
+%% This is a reasonable set of options to use for edown, but edown
+%% doesn't actually use rebar to make its own docs.
+%% {edoc_opts, [{doclet, edown_doclet},
+%% {src_path, ["src", "test"]},
+%% {app_default,"http://www.erlang.org/doc/man"}]}.
View
@@ -17,7 +17,7 @@
{application, edown,
[
- {vsn, "0.1"},
+ {vsn, "0.2.0"},
{description, "Markdown extension for EDoc"},
{applications, [kernel, stdlib]},
{mod, {jobs_app, []}},
View
@@ -141,13 +141,13 @@ gen(Sources, App, Packages, Modules, FileMap, Ctxt) ->
edoc_lib:write_info_file(App, Packages, Modules1, Dir),
copy_stylesheet(Dir, Options),
copy_image(Dir),
+ make_top_level_README(Data, App, Options),
%% handle postponed error during processing of source files
case Error of
true -> exit(error);
false -> ok
end.
-
set_app_default(Opts) ->
case lists:keyfind(app_default,1,Opts) of
false ->
@@ -156,8 +156,68 @@ set_app_default(Opts) ->
Opts
end.
+make_top_level_README(Data, App, Options) ->
+ case proplists:get_value(top_level_readme, Options) of
+ undefined ->
+ ok;
+ {Dir, Filename} ->
+ case App of
+ ?NO_APP ->
+ erlang:error(missing_app_name, [Data,App,Options]);
+ _ ->
+ make_top_level_README(Data, App, Dir, Filename)
+ end
+ end.
+
+make_top_level_README(Data, App, Dir, F) ->
+ Branch = get_git_branch(),
+ Exp = [xmerl_lib:expand_element(D) || D <- Data],
+ New = [xmerl_lib:mapxml(
+ fun(#xmlElement{name = a,
+ attributes = Attrs} = E) ->
+ case redirect_href(Attrs, App, Branch) of
+ {true, Attrs1} ->
+ E#xmlElement{attributes = Attrs1};
+ false ->
+ E
+ end;
+ (Other) ->
+ Other
+ end, Exp1) || Exp1 <- Exp],
+ Text = xmerl:export_simple_content(New, edown_xmerl),
+ edoc_lib:write_file(Text, Dir, F).
+
+redirect_href(Attrs, App, Branch) ->
+ AppBlob = atom_to_list(App) ++ "/blob/" ++ Branch ++ "/",
+ case lists:keyfind(href, #xmlAttribute.name, Attrs) of
+ false ->
+ false;
+ #xmlAttribute{value = "/" ++ _} ->
+ false;
+ #xmlAttribute{value = Href} = A ->
+ case re:run(Href, ":", []) of
+ {match, _} ->
+ false;
+ nomatch ->
+ HRef1 = AppBlob ++ Href,
+ {true,
+ lists:keyreplace(
+ href, #xmlAttribute.name, Attrs,
+ A#xmlAttribute{value = HRef1})}
+ end
+ end.
+
+get_git_branch() ->
+ case os:cmd("git branch | awk '/\\*/ {print $2}'") of
+ [_,_|_] = Res ->
+ %% trailing newline expected - remove.
+ lists:reverse(tl(lists:reverse(Res)));
+ Other ->
+ erlang:error({cannot_get_git_branch, Other})
+ end.
+
%% Tried to display logo in a table on top of page, but not working.
-%% Presumably, this hits some limitation of GFM
+%% Presumably, this hits some limitation of Markdown
%%
%% logo() ->
%% {img, [{src, "erlang.png"},{alt,["Erlang logo"]}],[]}.
View
@@ -191,7 +191,7 @@ within_html(Tags) ->
needs_html(T) ->
needs_html(T, []).
-needs_html(T, Attrs) ->
+needs_html(T, _Attrs) ->
lists:member(T, [table,'div',h1,h2,h3,h4,dd,dt,local_defs,localdef]).
no_nl(S) ->

0 comments on commit f0159e5

Please sign in to comment.